Re: Improvements to the Sphinx in-tree documentation generation

2013-12-17 Thread Jeff Walden
On 12/16/2013 03:09 PM, Gregory Szorc wrote: Perhaps Reflect.parse() could grow a new option to expose comment nodes or could attach comment metadata to specific node types? It's really not possible to do the latter. Comments don't appertain to specific nodes at all. They're just random

Re: Improvements to the Sphinx in-tree documentation generation

2013-12-16 Thread Gijs Kruitbosch
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? This makes me sad because it means I probably have to end up copy-pasting my source code documentation elsewhere either way (in which

Re: Improvements to the Sphinx in-tree documentation generation

2013-12-16 Thread Gregory Szorc
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

Re: Improvements to the Sphinx in-tree documentation generation

2013-12-16 Thread Jeff Walden
On 12/16/2013 01:17 PM, Gregory Szorc wrote: Does SpiderMonkey expose documentation blocks to the AST? If not, should it? No, and probably not. Comments are not tokens, so they're not in the AST. Right now SpiderMonkey pretty much just throws them away (except to the extent the comment

Re: Improvements to the Sphinx in-tree documentation generation

2013-12-16 Thread Gregory Szorc
On 12/16/13, 10:46 AM, Jeff Walden wrote: On 12/16/2013 01:17 PM, Gregory Szorc wrote: Does SpiderMonkey expose documentation blocks to the AST? If not, should it? No, and probably not. Comments are not tokens, so they're not in the AST. Right now SpiderMonkey pretty much just throws them

Re: Improvements to the Sphinx in-tree documentation generation

2013-12-16 Thread Eric Shepherd
On December 16, 2013 at 1:21:06 PM, Gregory Szorc (g...@mozilla.com) wrote: 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

Re: Improvements to the Sphinx in-tree documentation generation

2013-12-16 Thread Brandon Benvie
On 12/16/2013 12:57 PM, Andrew Sutherland wrote: The Esprima JS parser can already generate comment nodes. The API otherwise conforms to the same output standards as SpiderMonkey's Parser API. There's also acorn, which is an ES5 parser written in JS that's in the tree

Improvements to the Sphinx in-tree documentation generation

2013-12-12 Thread Gregory Szorc
After I announced the in-tree build docs powered by Sphinx a few months ago [1], a few people came to me and said that's really cool - I want something like that for my module. I'm pleased to announce that as of bug 939367 landing in inbound a few hours ago, you can now deposit Sphinx docs