Redo doc tags in widgets.js to match tags in assertion.js



8 years ago
8 years ago


(Reporter: gmealer, Assigned: gmealer)


Firefox Tracking Flags

(Not tracked)


(Whiteboard: [module-refactor])


(1 attachment)

Henrik's tagging is much cleaner than mine. Try his scheme in widgets.js.
Created attachment 519805 [details] [diff] [review]
Cut unnecessary tags out of the widgets.js docs

Removed @name and @memberOf tags from constructors and methods, also changed the  lends to widgets.Foo.prototype.

The extra tags are still necessary for properties, since jsdoc doesn't automatically recognize them and we have to @name them. Turns out the rule is anything that has to be @named also has to be hinted as to what type of structure it is and who it belongs to.

Generated docs are at:

Github branch:
Attachment #519805 - Flags: review?(hskupin)
Comment on attachment 519805 [details] [diff] [review]
Cut unnecessary tags out of the widgets.js docs

>+  /** foo */
>   _getCollector: function Element_getCollector() {

Is that a left-over or has it been forgotten? Even private methods should get a documentation to clarify its underlying functionality. Then we can simply add @private to not make it appear in the docs for tests.

Attachment #519805 - Flags: review?(hskupin) → review+
The /** foo */ was artifact of one of my "make the docs work" tests. I'll remove it.

The method, like all the other private methods, does have standard // documentation inside it as to how it works.

Re: jsdocing private methods, I don't agree with you. Private methods shouldn't be used by anybody but that object (including inheritors, as a general rule). We'll discuss offline.
Removed the "foo" artifact and landed on master:

Depending on the results of our discussion on doc'ing private methods, I'll file additional bugs to handle followup work.
Last Resolved: 8 years ago
Resolution: --- → FIXED
You need to log in before you can comment on or make changes to this bug.