On 12/16/13, 12:58 AM, Gijs Kruitbosch wrote:
From what I've been able to tell from the interwebs, extracting
documentation (autodoc-fashion) from JS/C++/IDL isn't possible with
Sphinx. Is that correct?
It is possible.
Sphinx can consume Doxygen's XML output to generate C++ docs via Breathe
[1]. I experimented with this during Summit, but one of Doxygen or
Sphinx was allocating 10+ GB memory trying to build the docs for all of
the tree and made my laptop at the time explode. We could probably make
things work by only reading part of the tree or incrementally generating
docs for the entire tree. There was also some XML Unicode encoding bug
in Doxygen I ran into. That's what happens when you attempt to construct
XML via string concatenation rather than going through an XML API (oh,
Doxygen). It would probably be pretty easy to write something against
the Clang API, since Clang's AST exposes parsed Doxygen doc entities [2].
As for JS and IDL, it's all /possible/. You just need a way to feed
stuff into Sphinx. If someone writes a tool that can extract JS
docblocks into a machine readable format, we can integrate them into
Sphinx. It's doable - I just don't think anyone has done it yet.
I agree our current mechanism for JS documentation is pretty bad. We
desire to document both the source and MDN for obvious reasons. But
nobody wants to burdened with writing docs twice. So typically in-tree
or MDN docs suffer. Neither is great for maintainability or consumers.
IMO we should just write in-tree source docs and export to MDN. Goodbye
syncing problem.
Are there any JS doc tools that can export to a machine readable format?
Does SpiderMonkey expose documentation blocks to the AST? If not, should it?
[1] http://michaeljones.github.io/breathe/
[2] http://clang.llvm.org/doxygen/group__CINDEX__COMMENT.html
_______________________________________________
dev-platform mailing list
dev-platform@lists.mozilla.org
https://lists.mozilla.org/listinfo/dev-platform
