search

AaronNGray / jsdoc-toolkit

Automatically exported from code.google.com/p/jsdoc-toolkit
0 stars 0 forks source link

Formalize and diversify expression of built-in types #241

Closed GoogleCodeExporter closed 9 years ago

GoogleCodeExporter commented 9 years ago 
It looks like the examples at
http://code.google.com/p/jsdoc-toolkit/wiki/TagParam use the constructors
of these types.

1) I am not clear on other types like "undefined" and whether the lower
case form should be used. Likewise with null, etc. I would think it would
be most clear if the case wasn't changed.

2) I think there should also be a way to distinguish constructed objects
from literals, since, e.g., String() and string literals can differ in
behavior when eval'd:
https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/St
ring
).

3) I also do not find mention in the docs on what the behavior will be when
something that is not one of these types is specified. Will it be assumed
to be a class indicating an object's type, or will it search for that
variable in the code and detect the type from it?

Original issue reported on code.google.com by bret...@gmail.com on 25 Aug 2009 at 10:39

GoogleCodeExporter commented 9 years ago 
This is not an issue that is internal to JsDoc Toolkit and thus not one I can 
fix. It is a matter of convention 
within your own project if you wish to distinguish between Objects and 
primitives when documenting the 
expected types of things. There is nothing within my code that will stop you 
from writing the following:

/**
 * @constructor
 * @param {object|Object} options  Some options which can be either primitive or a formally constructed 
Object.
 */
MyClass = function(options) {
    /** 
     * This instance's options which is a primative.
     * @type object
     */
    this.options = options;
}

/**
 * Set a property.
 * @param {String} val  Value for the property which is a formally constructed String object.
 */
MyClass.prototype.setProp = function(val) {
    /** 
     * Some property that is a primitive string.
     * @type string
     */
    this.prop = val;
};

As for point 3: yes, if you document that a type is something you've already 
documented elsewhere, JsDoc 
Toolkit will link them up in the output so you can get from that reference back 
to the constructor definition.

Original comment by micmath on 12 Sep 2009 at 6:11

GoogleCodeExporter commented 9 years ago 
This was more of a suggestion for suggesting a convention on the 
documentation/wiki
pages (and your approach seems it might be helpful to spell out as such there). 
I
think it would help for moving between projects if there are some recognized
conventions in place, even if different projects might wish to specify at 
different
levels of detail.

As another example I'm running across, what convention might be used to 
indicate an
E4X object parameter was required to have a particular element child? Maybe 
something
like xml.html.body.a@href to indicate it was expected to have some anchor 
attribute
within an anchor inside a complete HTML document expressed as E4X ("xml" type)?

Original comment by bret...@gmail.com on 13 Sep 2009 at 11:17

GoogleCodeExporter commented 9 years ago 
I'd suggest that this is more of a conversation to have with the community than 
just the developer. Would you 
care to post your ideas to the mailing list?

Original comment by micmath on 13 Sep 2009 at 2:09