apify
apify copied to clipboard
jbalsas
@type issues
Case 1: For this case from CommandManager.js:
/**
* Map of all registered global commands
* @type Object.<commandID: string, Command>
*/
Type is truncated to: "Object.<commandID:". This may be related to #14
Case 2: For this case from Editor.js:
/** @type {boolean} Guard flag to prevent focus() reentrancy (via blur handlers), even across Editors */
var _duringFocus = false;
@type doesn't seem to be parsed when comment is in a single line.
Hey @redmunds, I think none of this can be considered a bug.
Case 1:
The type should be @type {Object.<commandId: string, Command>}. We have examples of this in many other places. As with many other cases, we could improve the logic inside dox to be a bit smarter than what we are right now, but this should be fixed in the docs.
Case 2:
I haven't found any place where tags can precede the variable description. Afaict if we want description and some tags, we need more than one line comment, otherwise, everything is considered the description.
What do you think?
@jbalsas
Case 1: Good catch -- I didn't notice that
Case 2: This is an enhancement request because I see so many cases. This format is similar to @param and @return formats where it's all in 1 line with description at end. Low priority since we can just change the comments.
About the second case, I'm very reluctant to add it to our fork.
The reason is that for the @param and @return tags, the cases you mention are covered in the spec. However, I don't see that's case for @type.
On one hand, I don't want to end up forcing Brackets to use apify because it's the only tool that understands some special convention. On the other, I don't want to force apify to use our fork of dox to be able to support such customizations. We should try to stick to the standards as much as possibe to avoid these kinds of vendor lock-ins.
I know we're fixing them in the docs, but what do you think?
I've been told that Annotating JavaScript for the Closure Compiler is the doc we should follow.
That doc is somewhat vague on the issue. For @type it simply shows @type {Type}. The only example is using multiple lines:
/**
* The message hex ID.
* @type {string}
*/
var hexId = hexId;
All of the other tags are shown with the same vague syntax, and some have single line examples while others have multiple line examples. The @const tag shows both single and multiple line examples. This seems to indicate to me that any of the types can be single or multiple lines.
From the Annotating JavaScript for the Closure Compiler doc, I followed this link path: https://code.google.com/p/jsdoc-toolkit/ https://github.com/jsdoc3/jsdoc http://usejsdoc.org/ http://usejsdoc.org/tags-type.html
You can see that the last page has examples of @type comments with both single line and multiple line comments. It would be very nice be able to specify it either way for all tags, but I'm not sure how much work that would be. In all of the places where I converted @type comments to multiple lines, it takes up a lot more vertical space, so you can't see as many vars at a time.