Page MenuHomePhabricator

[Spike, 4hrs] What does jsdoc not support that jsduck does
Closed, ResolvedPublic

Description

In order to know if it is a good idea to migrate to jsdoc, we need to know what things does jsduck do that jsdoc doesn't and if there are alternatives.

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

List and alternatives

Are there other tools that could be used instead of jsdoc?


Features that jsduck provides and why it was chosen listed:

Here's a summary of some of JSDuck's features that I believe made it our choice originally:

  • User-friendly interface.
  • Search feature. (Client-side, serverless)
  • Stable permalinks to classes and methods.
  • Support Markdown for all text content.
  • Easy discovery through a browsable class hierarchy. (e.g. Sidebar shows "mw.Title" class nested in "mw" singleton)
  • Support for class inheritance and mixins, and pages include inherited members by default.
  • Support for singletons.
  • Support for private members.
  • Support for static members.
  • Support for events.
  • Support for documenting which events are emitted by a method. (@fires)
  • Support for private classes.

These less-essential features are also quite nice:

  • Interface allows toggling private members and private classes (and hidden by default).
  • Interface shows in which file(s) a class is defined.
  • Each class page show class hierarchy and mixins, in both directions.
  • Live examples using @example that make for interactive demos in the context of documentation. Especially useful to help understand how UI library works and which widgets to use.
  • Classes organised by group, on the homepage. ("Categories")
  • Easy to extend with additional tags. (@context, @see, @since, etc.)
  • Intelligent linking to mentioned classes and methods. ("Foo bar #baz")
  • Support for documenting properties of parameters that are objects.
  • Support for documenting properties of returned objects.
  • Support for documenting callback parameters.
  • Support for documenting upstream code with pure comments. ("jsduck.external.js")
  • Support for class aliases.
  • Type validation (unknown param or return type produces an error.)

Of course, we've also come across various limitations over time:

  • Event names cannot contain dots. jsduck #497 (wikipage.content documented as wikipage_content)
  • There cannot be a class and singleton with the same case-insensitive name. jsduck #304 (mw.notification and mw.Notification documented as mw.Notification_)
  • No concept of "modules", which would allow grouping classes together. As well as allowing methods to be documented as being part of a module without having a global class (e.g. module.exports). jsduck #553
  • No longer actively maintained.
  • Written for Ruby instead of Node.js.
  • No support for ES6 syntax. T156469. jsduck #630

Timebox: 4hrs

Event Timeline

Jhernandez removed Volker_E as the assignee of this task.Sep 28 2016, 4:55 PM
Jhernandez added a subscriber: Volker_E.
Jhernandez updated the task description. (Show Details)Mar 6 2017, 3:36 PM
Jdlrobson lowered the priority of this task from High to Medium.Apr 20 2017, 11:04 PM
Jdlrobson renamed this task from Spike: What does jsdoc not support that jsduck does to [Spike, 4hrs] What does jsdoc not support that jsduck does.May 16 2017, 3:51 PM
Jdlrobson updated the task description. (Show Details)

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:

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 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.

Jdlrobson removed Jdlrobson as the assignee of this task.May 31 2017, 5:08 PM
Jhernandez moved this task from Needs More Work to Doing on the Readers-Web-Kanbanana-Board-Old board.
kaldari removed a subscriber: kaldari.Jun 2 2017, 6:38 PM

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

Jhernandez added a comment.EditedJun 5 2017, 12:39 PM

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.

Jhernandez updated the task description. (Show Details)Jun 7 2017, 5:30 PM

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.

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

phuedx closed this task as Resolved.Jun 9 2017, 9:28 AM

Nice work, @Jhernandez 👌 💥💥💥

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