Change 355720 had a related patch set uploaded (by Jdlrobson; owner: Jdlrobson):
[mediawiki/extensions/MobileFrontend@master] POC: Switch from jsduck to jsdoc in MobileFrontend extension

https://gerrit.wikimedia.org/r/355720

What does jsduck do that we wouldn't be able to do in jsdoc?

I took a look at MobileFrontend given its our largest extension and tried to switchover.

Problems:

• No support for @inheritdoc
• Methods are being documented as globals rather than part of the class. As demonstrated in View.js our existing style would require us to use memberof in all method declarations
  • The lack of support for detecting whether memberof declarations are missing is concerning. It could lead to bad documentation. Manual steps always create this problem.

I think if we can avoid the use of @memberOf and get support for @inheritdoc then I think it would be trivial for us to move over to this.
I think the OOjs UI team avoid the use of @memberOf by directly assigning to the prototype like so:

Foo.prototype.methodName = function () {

We could of course do this in MobileFrontend but that would be a very big rewrite to change existing code styling conventions and I'd rather avoid it.

@Krinkle @Volker_E @kaldari @matmarex do we have ways to do @inheritdoc and @memberOf with jsdoc?

See also: [Wikitech-l] use of @inheritdoc

What about using some strong-typed JS implementation like TypeScript? It comes with big refactor (if we want to use it everywhere from the beginning - but TS allows us to write only new code using TypeScript plus every valid Javascript code is also valid TypeScript code) plus TypeDoc is pretty nice. I'm OO person, adding @memberof annotation everywhere looks really silly - it's a huge 👎

That happens because we use a custom class system. There is @lends for that: http://usejsdoc.org/tags-lends.html

The @lends tag allows you to document all the members of an object literal as if they were members of a symbol with the given name. You might want to do this if you are passing an object literal into a function that creates a named class from its members.

I've made a followup to the POC, https://gerrit.wikimedia.org/r/#/c/356366/ See @lends in action in View.js and http://mobilefrontend-jsdoc-test.surge.sh/View.html

No support for @inheritdoc

http://usejsdoc.org/tags-inheritdoc.html ?

I've checked and it seems to work properly if the prototype is well set up. See for example [Overlay#postRender](http://mobilefrontend-jsdoc-test.surge.sh/Overlay.html#postRender)

Things I've noticed:

• @cfg does not exist.
  • Can be changed with @property, see https://gerrit.wikimedia.org/r/#/c/356366/2/resources/mobile.startup/Overlay.js
    • Without @inheritdoc, it automatically shows it is overriden, and great table with the info: http://mobilefrontend-jsdoc-test.surge.sh/Overlay.html#defaults
• @inheritdoc is useless
  • JSDoc will mark overriden methods with the docs from parents without the need to specifying the tag or even a comment
  • Any other things that you specify will be ignored if you use @inheritdoc. So our technique of adding @inheritdoc and then adding more text and stuff will be ignored.
  • See docs:

The @inheritdoc tag indicates that a symbol should inherit its documentation from its parent class. Any other tags that you include in the JSDoc comment will be ignored.

This tag is provided for compatibility with Closure Compiler. By default, if you do not add a JSDoc comment to a symbol, the symbol will inherit documentation from its parent.

• The description of a class looked like crap, I had to add the markdown plugin, and use @classdesc so that the description is of the class and not of the constructor function. Now it looks great: http://mobilefrontend-jsdoc-test.surge.sh/View.html
• On a constructor function, the docs are for the constructor. For documenting a class like we usually do we have to use @classdesc.
  • See https://gerrit.wikimedia.org/r/#/c/356366/2/resources/mobile.startup/View.js
• @mixins Doesn't exist, instead it is [@mixes](http://usejsdoc.org/tags-mixes.html#syntax)

The reality is that JSDoc seems very similar but it is different, so we shouldn't be expecting a straightforward migration, and we are going to need to refer to the docs and learn how to use it properly if we want to migrate.

On the other side, it seems pretty solid and it seems to support most of the javascript patterns.

@Jdlrobson Is there anything else that seems like we couldn't do?
@phuedx You've been touching JSDoc too, do you have any thoughts?

I was hoping to see from the list on the description what JSDoc does and what it does not (of the reasons why jsduck was chosen).

I'm happy to do it.

Going to be starting work here https://www.mediawiki.org/wiki/User:JHernandez_(WMF)/JS_documentation_tools

Change 356366 had a related patch set uploaded (by Jhernandez; owner: Jhernandez):
[mediawiki/extensions/MobileFrontend@master] POC: JSDOC improvements

https://gerrit.wikimedia.org/r/356366

Change 357202 had a related patch set uploaded (by Jhernandez; owner: Jhernandez):
[mediawiki/extensions/MobileFrontend@master] POC: JSDoc Docstrap template and other tests

https://gerrit.wikimedia.org/r/357202

I've completed the list for JSDoc, will have a look at documentation.js next
https://www.mediawiki.org/wiki/User:JHernandez_(WMF)/JS_documentation_tools

I have https://esdoc.org/ on my radar too.

Change 357583 had a related patch set uploaded (by Jhernandez; owner: Jhernandez):
[mediawiki/extensions/MobileFrontend@master] POC: Use documentation.js to generate docs

https://gerrit.wikimedia.org/r/357583

esdoc has been discarded because it only supports modern es2015 classes. So no prototype based ones or custom class creators.

Please give a read at https://www.mediawiki.org/wiki/User:JHernandez_(WMF)/JS_documentation_tools and provide feedback. If all OK let me know and I'll migrate the page under Reading/web/ and link to it on the frontend standards group for future discussion.

Could you update https://www.mediawiki.org/wiki/User:JHernandez_(WMF)/JS_documentation_tools with a recommendation from yourself? e.g. should we switch or not? If so under what conditions?

@Jdlrobson I've added [[ https://www.mediawiki.org/wiki/User:JHernandez_(WMF)/JS_documentation_tools#Recommendations | JS_documentation_tools#Recommendations ]]

Let me know if it reads well and answers your questions.

@Jhernandez On first impression that looks good to me, a solid resource for further discussion in next front-end dev meeting.

LGTM @Jhernandez!

Great! @bmansurov @phuedx @pmiazga feel free to signoff, since me and Jon worked on it.

Change 357583 abandoned by Jdlrobson:
POC: Use documentation.js to generate docs

Reason:
POC. https://phabricator.wikimedia.org/T146917 is resolved.

https://gerrit.wikimedia.org/r/357583

Change 357202 abandoned by Jdlrobson:
POC: JSDoc Docstrap template and other tests

Reason:
https://phabricator.wikimedia.org/T146917 is resolved

https://gerrit.wikimedia.org/r/357202

Change 356366 abandoned by Jdlrobson:
POC: JSDOC improvements

Reason:
https://phabricator.wikimedia.org/T146917 is resolved

https://gerrit.wikimedia.org/r/356366

Change 355720 abandoned by Jdlrobson:
POC: Switch from jsduck to jsdoc in MobileFrontend extension

Reason:
just a POC

https://gerrit.wikimedia.org/r/355720