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

RESOLVED FIXED

Status

RESOLVED FIXED
8 years ago
8 years ago

People

(Reporter: gmealer, Assigned: gmealer)

Tracking

Firefox Tracking Flags

(Not tracked)

Details

(Whiteboard: [module-refactor])

Attachments

(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:

http://people.mozilla.com/~gmealer/docs/ms1-leandocs/

Github branch: 

https://github.com/geoelectric/mozmill-api-refactor/tree/ms1-leandocs
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.

r=me.
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: https://github.com/geoelectric/mozmill-api-refactor/commit/2077b35d84095b3b360cb597a20cffafdd9a9828

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