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

Status: RESOLVED FIXED

(Mozilla QA Graveyard :: Mozmill Tests, defect)

Description

[Geo Mealer [:geo] -- This account is inactive after 2015-07-07]

Henrik's tagging is much cleaner than mine. Try his scheme in widgets.js.

Comment 1

[Geo Mealer [:geo] -- This account is inactive after 2015-07-07]

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

Comment 2

[Henrik Skupin [:whimboo][⌚️UTC+1]]

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.

Comment 3

[Geo Mealer [:geo] -- This account is inactive after 2015-07-07]

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.

Comment 4

[Geo Mealer [:geo] -- This account is inactive after 2015-07-07]

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.