Open jonschlinkert opened 5 years ago
@tunnckoCore how do you want to divide up the tasks? Do you want to do unit tests? Or convert filters? Or both?
Or we can each pick a few categories of filters to work on.
I can handle the tests and few categories.
We can continue with this pattern until we're ready to publish, then we can remove dupes
Ookey.
I can handle the tests and few categories.
Awesome! Let me know which categories you're going to do so I don't do the same ones. thanks!
The color
and money
ones.
sounds good!
@tunnckoCore if you remember, try to put the methods in alphabetical order so we can more easily scan for missing/duplicate filters. Not a big deal.
Yea, was thinking about that too. Btw, should we preserve the underscore naming? I don't think so, because we are in the JavaScript land and linters may signal errors if users follow camelcase or other convention.
Btw, should we preserve the underscore naming?
Yeah, let's keep the underscores. I know it sucks, I agree - I don't like them personally either. My main goal is to make it really easy for Jekyll users to switch to another framework. We can easily create aliases for those though.
Edit: also it will make it a lot easier for us to scan the filters on liquid libs and check for parity.
linters may signal errors if users follow camelcase or other convention.
We can figure this out before we publish. Maybe we'll create a "name mapper" for aliases, so we can use camelcase, but for now IMHO it will make this easier if we stick to the same names.
One more thing... I'm trying to make most of the filters generic, but there are a few that have options.hash
in them, which is a handlebars syntax. The reason is that those were ported from liquid "tags", which are more like handlebars block helpers, and there is no good way to port those to single line helpers that are template-engine-agnostic. We need to figure out a good way to expose those, maybe on a block
property, or tags
or something, but for now it's something to think about.
@tunnckoCore I just pushed up. Hopefully you don't get any conflicts, I didn't touch tests or the filters you're working on (do you get notifications when someone pushes up to a repository you collaborate on?)
No, everything is good. I'm working on a branch too ;d
do you get notifications
Yea, it's not a problem to me, I always have tons of notif cuz I watch tons of repos.
K, here is an example of how I'm doing comments. Don't worry too much about these, I can edit:
/**
* Truncate a string to the specified `length`, and append
* it with an elipsis, `…`.
*
* ```html
* {{ "<span>foo bar baz</span>" | ellipsis: 7 }}
* <!-- Results in: 'foo bar…' -->
* ```
* @param {String} str
* @param {Number} length The desired length of the returned string.
* @param {String} suffix (optional) Custom characters to append. Default is `…`.
* @return {String} The truncated string.
* @api public
*/
exports.ellipsis = (str, len, suffix) => {
return isString(str) ? (exports.truncate(str, len) + (suffix || '…')) : '';
};
I'm debating whether or not we should do the code examples in the comments, or if we should do them separately in docs.
Several years ago I created a code comment linter that reported how many methods were undocumented and a few other useful stats. IMHO that might be a good solution here. I have something we can use if we want to go this route.
edit: it would be awesome if our docs had examples for several template engines, but comments like the following are just too verbose and hard to maintain:
/**
* Pads the given string with another string until the resulting
* string reaches the specified maxiumum length. The padding is
* applied from the end (right) of the current string.
*
* ```js
* <!-- Signature: string.pad_end(str, maxLength[, padString]) -->
* Liquid: {{ "Foo" | pad_end: 10, "0" }}
* Handlebars: {{pad_end "Foo" 10 "0"}}
* ejs: <%= pad_end("Foo", 10, "0") %>
* <!-- Results in: 'Foo0000000' -->
* ```
* @param {String} str
* @param {String} maxLength
* @param {String} padString
* @return {String}
* @api public
*/
I have an idea... I'll create another issue.
What about just using multiple @example
s?
/**
* Pads the given string with another string until the resulting
* string reaches the specified maxiumum length. The padding is
* applied from the end (right) of the current string.
*
* @example hbs
* <h1>{{ pad_end "Foo" 10 "0" }}</h1>
*
* @example liquid
* <h1>{{ "Foo" | pad_end: 10, "0" }}</h1>
*
* @example ejs
* <h1><%= pad_end("Foo", 10, "0") %></h1>
*
* @param {String} str
* @param {String} maxLength
* @param {String} padString
* @return {String}
* @public
*/
It not looks that bath bad, both in code and in docs.
I’m not a big fan of that format. It’s based on javadoc and IMHO it looks messy.
Sent from my iPhone
On Nov 25, 2018, at 10:53 PM, Charlike Mike Reagent notifications@github.com wrote:
What about just using multiple @examples?
/**
- Pads the given string with another string until the resulting
- string reaches the specified maxiumum length. The padding is
- applied from the end (right) of the current string.
- @example hbs
{{ pad_end "Foo" 10 "0" }}
- @example liquid
{{ "Foo" | pad_end: 10, "0" }}
- @example ejs
<%= pad_end("Foo", 10, "0") %>
- @param {String} str
- @param {String} maxLength
- @param {String} padString
- @return {String}
- @public */ — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub, or mute the thread.
And what? I noticed that you are not fan (in the tokenize-comment
), but why? it has great syntax highlighting support everywhere. And completely make sense.
Should we throw from the helpers or just to return an empty string?
Should we throw from the helpers or just to return an empty string?
The convention with most template engines is to just return an empty string. I assume this is because it's better than having undefined
in your generated HTML and/or requiring the user to write conditional code in templates to populate an empty string when the value is undefined.
Honestly, I've never felt good about either option here. What are your thoughts? @doowb?
And what? I noticed that you are not fan (in the
tokenize-comment
), but why? it has great syntax highlighting support everywhere. And completely make sense.
I'm not sure what you mean. tokenize-comment
parses those completely, even when there are multiple of them. I just don't like using them in my own comments, I personally find them harder to read. Using very light markdown syntax makes the comments formatted more similarly to the actual documentation used in markdown, which makes it easier for the user to glance at the code and figure out what's going on. just my 2c.
I just added more javadoc tests so you can see what I mean. Let me know if I'm not understanding what you mean.
Honestly, I've never felt good about either option here.
I think they should still throw but the template engine to handle that cases, so users will immediately understand what happens. It is always better to inform the user instead of giving him some undefined
or empty strings.
I'm not sure what you mean. tokenize-comment parses those completely, even when there are multiple of them.
Yea yea, I know. I got your point, it's personal preference.
Using very light markdown syntax makes the comments formatted more similarly to the actual documentation
Actually no. :laughing: It seems weird. Because in the api docs they see the actual example code, syntax highlighted, but in the code comments they see some gfm fence block, which isn't highlighted... Yes, with @example
it still isn't highlighted, but at least you immediately see where the code example starts and ends. Only because the @example
is marked as tag.
Actually no. 😆 It seems weird. Because in the api docs they see the actual example code, syntax highlighted, but in the code comments they see some gfm fence block, which isn't highlighted.
So, to be clear, you are saying that this "seems weird"
which renders to
because... even though it's identical to what's in the code comment, the @example
tag, which looks like this:
...makes it easier to see where the example begins and ends? You think that's more obvious than ```
?
Okay, I'm totally cool with people having different opinions, and it's 100% fine if you just prefer @example
for whatever reason. But there is no universe in which that is more clear. We'll have to agree to disagree on this one lol.
Honestly, the reason I don't like @example
is that it always looks like someone commented out code and forgot to remove it, until I do a double take.
I don't think indentation for the @example
tag is needed? Also it seems like your editor theme do not highlight the tags?
Isn't it obvious where the example end? :laughing:
Which renders absolutely the same as in the code comment...
Also it seems like your editor theme do not highlight the tags?
Haha, I disable that. I don't like when code comments are colored similar to the actual code. It's just my preference. I find it distracting.
Tests
There are other javascript ports of liquid, we can probably get more tests and filters from those as well.
cc @tunnckoCore @doowb