On 7/2/2014 12:01 PM, Gregory Szorc wrote:
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.)
Doxygen can leverage libclang (set CLANG_ASSISTED_PARSING to YES).
There's still the not-insignificant problem with documentation that all
of our build files have a crazy, insane, inconsistent set of command
lines that make the -I and -D state unpredictable, and I don't think
Doxygen can tolerate per-file command lines.
(And Doxygen's parser isn't Perl-based, it's yacc-based.) The problem is
that Doxygen does a very good job of turning comments into
documentation, it is just extremely lousy at handling C++ code (the
author, for example, has repeatedly refused to support the GCC
__attribute__(()) productions...). It doesn't look like there's an easy
way to bypass the parser and just have it operate on comments :-(
--
Joshua Cranmer
Thunderbird and DXR developer
Source code archæologist
_______________________________________________
dev-platform mailing list
dev-platform@lists.mozilla.org
https://lists.mozilla.org/listinfo/dev-platform
