JS API docs for mozilla-central

Robert Helmer rhelmer at mozilla.com
Tue Nov 21 18:16:32 UTC 2017


Hello,

As of bug 1389341, we now have a way to automatically generate and
host JS API docs for every mozilla-central push.

We currently do have API docs for many components on MDN, but these
are largely out of date (at least in my experience) and likely to be
culled as MDN re-focuses on web content and away from Mozilla-specific
technologies [1].

Here is a quick example, for the public AddonManager API:
https://firefox-source-docs.mozilla.org/toolkit/mozapps/extensions/addon-manager/AddonManager.html

To use it for your own code:
1) Check that JSDoc generates the output you expect (you may need to
use a @class annotation on object initializer style definitions for
instance[2])
2) Create an .rst file, which may contain explanatory text as well as
the API docs. The minimum will look something like
https://firefox-source-docs.mozilla.org/_sources/toolkit/mozapps/extensions/addon-manager/AddonManager.rst.txt
3) Ensure your component is on the js_source_path here in the sphinx
config: https://hg.mozilla.org/mozilla-central/file/72ee4800d415/tools/docs/conf.py#l46
4) Run `mach doc` locally to generate the output and confirm that it
looks correct

That should be it! The "Doc" taskcluster job will now generate your
API docs, and they will be automatically published on
firefox-source-docs.mozilla.org

Thanks to Erik Rose for writing sphinx-js [3] and helping to integrate
it and gps for standing up the docs and fixing the hosting situation!


-Rob

1 - https://blog.mozilla.org/opendesign/future-mdn-focus-web-docs/

2 -  Also note that AddonManager uses the "AddonManager forwards to
AddonManagerInternal" pattern. It was recently discussed here whether
we can stop using this pattern, but in the meantime it's possible to
accommodate it with a combination of @private for private methods and
@lends:
https://hg.mozilla.org/mozilla-central/file/72ee4800d415/toolkit/mozapps/extensions/AddonManager.jsm#l626

3 - https://hacks.mozilla.org/2017/07/introducing-sphinx-js-a-better-way-to-document-large-javascript-projects/


More information about the firefox-dev mailing list