API docs for JS in mozilla-central

Kris Maglione kmaglione at mozilla.com
Tue Nov 21 18:21:05 UTC 2017


Thank you for finally making this happen. I've been wanting to 
do this for the code that I work on for years, now...

On Tue, Nov 21, 2017 at 10:16:32AM -0800, Robert Helmer wrote:
>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:
>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
>2) Create an .rst file, which may contain explanatory text as well as
>the API docs. The minimum will look something like
>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
>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!
>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
>3 - https://hacks.mozilla.org/2017/07/introducing-sphinx-js-a-better-way-to-document-large-javascript-projects/
>firefox-dev mailing list
>firefox-dev at mozilla.org

Kris Maglione
Senior Firefox Add-ons Engineer
Mozilla Corporation

There is no greater mistake than the hasty conclusion that opinions
are worthless because they are badly argued.
	--Thomas Huxley

More information about the firefox-dev mailing list