API docs for JS in mozilla-central

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


\o/

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:
>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/
>_______________________________________________
>firefox-dev mailing list
>firefox-dev at mozilla.org
>https://mail.mozilla.org/listinfo/firefox-dev

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