646228 - Generate up-to-date JSDocs for Gloda and Mozmill

Status: RESOLVED WORKSFORME

(MailNews Core :: Database, defect)

Description

[Jonathan Protzenko [:protz]]

Per discussion on tb-planning [https://mail.mozilla.org/pipermail/tb-planning/2011-March/000873.html], we should try to see what jsdoc comes up with when run on mailnews/db/gloda and mail/test/mozmill.

Comment 1

[Andrew Sutherland [:asuth] (he/him)]

Noting that I would suggest that if it does not yield fruit pretty quickly, I would suggest we reconsider and try with another tool.  Specifically, my previous tooling efforts in this area may be of use, and I think that, assuming reasonably comparable efforts, it's better to sink more time into them/a relative/something else more JS-y than JSDoc (toolkit).  (And it would definitely be preferable to not have to add the specific markup tags required because JSDoc needs to be told things explicitly.)

Comment 2

[Jonathan Protzenko [:protz]]

So I gave this a shot, and the results are disappointing. First, some links:
- http://yquem.inria.fr/~protzenk/mozmill-doc/
- http://yquem.inria.fr/~protzenk/gloda-doc/

Here's some problems we have with the current docs:
- some classes are missing for gloda (e.g. MimeMessage)
- some formatting is lost for Gloda, I wonder if I didn't pass the right switches to jsdoc, I'll try to investigate that,
- for mozmill, there's no way to group the functions *by file*, that's completely unacceptable! this renders the whole doc unusuable.

I'll try to see if I can fix these pain points easily, but if not (which looks plausible enough), we may have indeed to switch to your other documentation tools.

Comment 3

[Adrian Aichner [:anaran]]

I have been experimenting with https://github.com/jsdoc3/jsdoc as of late, and it is a bit of a rough start.

It does not produce any output until you put in tags like @fileoverview, @class, @global.

But then it is pretty nice, especially with the jaguarjs templates (which currently fail to link to the global.html file, see https://github.com/davidshimjs/jaguarjs-jsdoc/issues/5).

Is an effort started by this bug report in progress or completed anywhere?

Comment 4

[Andrew Sutherland [:asuth] (he/him)]

The stuff I was working on in comment 1 is abandoned.  I'd assume :protz's work in comment 2 is likely rendered moot by the extensive changes to JSDoc for version 3 (which is pretty neat).  I'm going to speculatively clear the assignee on this since I know :protz is quite busy with non-Thunderbird stuff.

I think you should feel free to assign the bug to yourself and work on this if you're interested and/or having jsdoc process other parts of the Thunderbird/MailNews trees too.

Comment 5

[Wayne Mery (:wsmwk)]

Adrain, are you willing to work on this?

Comment 6

[Adrian Aichner [:anaran]]

Where would I start working on this and what would be a small first step that would already be useful to the project?

Comment 7

[Kent James (:rkent)]

I realize that we have tried very hard to use markup standards in writing code, but I have never used any documentation other than what is in the code itself. Who is the target audience for this jsdoc documentation?

My fear is that trying to maintain jsdoc-compatible documentation is likely to require a level of discipline in code review that we are unlikely to be able to achieve, so any effort to improve this will quickly become non-useful as the actual code diverges in some way from the jsdoc requirements.

But I don't have much experience in these areas I admit. Can someone explain to me how this is likely to be useful?

If someone were to come to me offering to help with Thunderbird and Mailnews documentation, I would probably point them to these two areas:

1) If you are interested in automated tools like jsdoc, try to apply that to code that has some hope of being useful outside of Thunderbird. The main candidate here is currently jsmime.

2) For general documentation issues, try to add minimal documentation to the many undocumented methods and attributes in core mailnews/base/public interfaces.

Comment 8

[Andrew Sutherland [:asuth] (he/him)]

I agree with :rkent.  This bug was filed when there were MoMo-funded fulltime engineering resources dedicated towards improving the extension-developer story for Thunderbird, and gloda, jetpack, and jetpack-for-thunderbird were actively envisioned to fulfil these roles.  Friendly documentation was an important aspect of those goals.  (Which is how we got https://github.com/asutherland/jstut and friends).  That's no longer the case, and there isn't anyone I'm aware of ready to answer questions about gloda on a beginner level, so it's probably better if people just directly consult the code.

(Note: However, I am available to answer questions for those actively contributing to/enhancing gloda, especially if the contributor is not entirely opposed to eventually taking over module ownership of gloda.)

I can say that if one was going to generate documentation, my most recent js documentation forays have suggested jsdoc3 is still the best choice.

Comment 9

[Magnus Melin [:mkmelin]]

mozmill is gone