On 7/2/14, 9:48 AM, Gijs Kruitbosch wrote:
On 02/07/2014 17:46, Joshua Cranmer 🐧 wrote:
On 7/2/2014 11:18 AM, Gregory Szorc wrote:
I find the current state extremely frustrating. I had big plans for
the in-tree docs, including capturing JavaScript docs and having JSM
APIs automatically published to MDN so we don't have to write docs
twice. If anyone is in a position to nudge this project forward, I'd
really appreciate the assist. We're mostly blocked on MDN
accommodations.
The problem I always had was the lack of a JS documentation tool that
could actually process Mozilla code...
Ditto. It might be nice to move the build docs to MDN, but most of our
code is not the build docs. Without good support for (our) JS and C++,
this is significantly less useful.
I'm not sure what exactly you mean by "less useful." I think you mean
"because we don't have JS and C++ docs it is less useful."
Sphinx can capture C++ docs. I don't have it enabled because Doxygen is
super slow. (I'm still waiting for someone to leverage Clang's superior
tooling to replace Doxygen or at least output its XML format so
Doxygen's Perl-based C++ parser can DIAF.)
Also, I experimented with extracting code comments from JavaScript using
Reflect.parse(). I'd still like an official SpiderMonkey API to extract
comments from the token stream. But it could be done manually post parse
time, if necessary. We could even consider teaching Esprima how to parse
Mozilla's extensions.
I figured I'd integrate everything with Sphinx because it is a rich
documentation platform. I'd welcome the opportunity to employ doctests
in our Python (and possibly JS as well) so we can write tests and
example code in one go. Lots of room for productivity wins here...
_______________________________________________
dev-platform mailing list
dev-platform@lists.mozilla.org
https://lists.mozilla.org/listinfo/dev-platform
