<div dir="ltr"><div style="font-size:12.8px"><div class="gmail-im">>> The backend modules would cover different possible outputs for the defined<br>>> intermediate representation. Each module will consume the representation and<br>>> output documentation in a specific format. Initially, we propose to focus on<br>>> a module that generates Markdown files, in order to make the first version<br>>> as simple as possible. Markdown files are automatically rendered on a number<br>>> of sites and systems, as well as being clear and uncluttered in raw text<br>?> form. It is also relatively easy to convert Markdown files into other<br>>> formats, making it a good starting target. An additional module would target<br>>> HTML/website output.<br><br></div></div><span style="font-size:12.8px">>While i understand the reasoning, I'm not sure the backends is a great idea.</span><br style="font-size:12.8px"><span style="font-size:12.8px">>TLDW: how about *only* outputting RST (well, or MD) and delegating the</span><br style="font-size:12.8px"><span style="font-size:12.8px">>rest to the sphinx? This *should* allow for native integration into sphinx-based</span><br style="font-size:12.8px"><span style="font-size:12.8px">>documentation, which is currently not achievable natively with Doxygen.</span><br><div><span style="font-size:12.8px"><br></span></div><div><span style="font-size:12.8px">We're looking to have something a little more flexible for the intermediate format than MD, to allow for a number of different formats for output in the future. The type of integration you're suggesting would be a great extension to the backend module that emits MD, which would be fairly easy to add into this. </span></div></div><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Dec 5, 2017 at 1:48 AM, Roman Lebedev <span dir="ltr"><<a href="mailto:lebedev.ri@gmail.com" target="_blank">lebedev.ri@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">On Mon, Dec 4, 2017 at 11:21 PM, Julie Hockett via cfe-dev<br>
<<a href="mailto:cfe-dev@lists.llvm.org">cfe-dev@lists.llvm.org</a>> wrote:<br>
Hi.<br>
I'm pretty much just a user, but i have some thoughts.<br>
<span class=""><br>
> This proposal is to build a new Clang tool for generating C/C++<br>
> documentation, similar to other modern documentation generators such as<br>
> rustdoc.  This tool would be a modular and extensible documentation<br>
> generator for C/C++ code. It also would introduce a more elegant way of<br>
> documenting C/C++ code, as well as maintaining backwards-compatibility with<br>
> Doxygen-style markup to generate documentation.<br>
><br>
> Today, Doxygen is a de-facto standard for generating C/C++ documentation.<br>
> While widely used, the tool itself is a bit cumbersome, its output is both<br>
> aesthetically and functionally lacking, and the non-permissive license<br>
> combined with outdated codebase make any improvements difficult. This new<br>
> tool would aim to simplify the overhead of generating documentation,<br>
> integrating it into a Clang tool as well as allowing existing comments to<br>
> continue to be used. It would also allow for relatively easy adaptation to<br>
> new language features, as it would be built on the Clang parser and would<br>
> use the Clang AST to generate documentation.<br>
</span>Sounds awesome so far.<br>
<div><div class="h5"><br>
> Proposed Tool<br>
><br>
> The proposed tool would consist of two parts. First, it would have a<br>
> frontend that consumes the Clang-generated AST and generates an intermediate<br>
> representation of the code and documentation structure, including additional<br>
> Markdown files. Second, it would have a set of backend modules that consume<br>
> that representation and output documentation in a particular format (e.g.<br>
> Markdown, HTML/website, etc.).<br>
><br>
> The frontend would be a new tool that uses the Clang parser, which can<br>
> already parse C/C++ documentation comments (using -Wdocumentation option).<br>
> It can be easily used through the LibTooling interface, similarly to other<br>
> Clang tools such as clang-check or clang-format. The initial steps in this<br>
> project would be to build this tool using Clang's documentation parser. This<br>
> tool would be able to attach comments to both functions, types, and macros<br>
> and resolve declaration references, both of which will be useful in<br>
> generating effective documentation. Since a good deal of existing C/C++ code<br>
> uses the Doxygen documentation comment style, which is also supported by<br>
> Clang's parser (and Doxygen itself can use Clang to parse these comments),<br>
> this is the syntax we are going to support as well. In the future, we would<br>
> also like to support Markdown-style comments, akin to Apple Swift Markup.<br>
><br>
> For implementation, this tool will use the JSON Compilation Database format<br>
> to integrate with existing build systems. It would also have subcommands to<br>
> choose which parts of the code will be documented (e.g. all code, all public<br>
> signatures, all comment-documented signatures). Once the code is processed,<br>
> the tool will write out the internal representation of the the documentation<br>
> in an intermediate representation, encapsulating the necessary information<br>
> about the code, comments, and structure. This will allow backend tools to<br>
> take the output and transform it as necessary.<br>
><br>
> The backend modules would cover different possible outputs for the defined<br>
> intermediate representation. Each module will consume the representation and<br>
> output documentation in a specific format. Initially, we propose to focus on<br>
> a module that generates Markdown files, in order to make the first version<br>
> as simple as possible. Markdown files are automatically rendered on a number<br>
> of sites and systems, as well as being clear and uncluttered in raw text<br>
> form. It is also relatively easy to convert Markdown files into other<br>
> formats, making it a good starting target. An additional module would target<br>
> HTML/website output.<br>
</div></div>While i understand the reasoning, I'm not sure the backends is a great idea.<br>
TLDW: how about *only* outputting RST (well, or MD) and delegating the<br>
rest to the sphinx? This *should* allow for native integration into sphinx-based<br>
documentation, which is currently not achievable natively with Doxygen.<br>
<span class=""><br>
> Intermediate Format<br>
><br>
> The frontend would process the code and comments into an output, to be<br>
> consumed by the backend. This representation would be internally represented<br>
> as a set of classes and structs. Once the frontend has finished, it would<br>
> write this representation to a file. While existing tools like Doxygen emit<br>
> XML, XML is somewhat restrictive and bulky. Also, in order to fully use XML,<br>
> the tool would need to define the representation twice (once for the<br>
> internal classes/structs, once in the XML schema). So, we are instead<br>
> considering two possible formats for this intermediate step: LLVM bitstream<br>
> and JSON/YAML.<br>
><br>
> LLVM bitstream format is space-efficient, and is natively written out by the<br>
> Clang parser. It has the benefit of being similar to existing clang<br>
> functionality, as the compiler frontend writes out its AST into the<br>
> bitstream format to pass along to the LLVM backend. Using this format would<br>
> allow the tool to emit the representation with minimal manipulation or<br>
> additional parsing.<br>
><br>
> Alternatively, JSON/YAML, while less space-efficient than bitstream, are<br>
> human-readable and widely extensible. Neither has formal grammar or<br>
> namespacing support, so if the tool needed rules of the sort it would need<br>
> to define them itself on the frontend and require that the backend modules<br>
> know them. While this would require a bit more parsing to emit on the<br>
> frontend and load on the backend, the representation would be able to stand<br>
> separately from the tool, and the backend modules would not necessarily need<br>
> an understanding of the LLVM bitstream to load it.<br>
<br>
</span>I'm not seeing any mention of graph/diagram generation.<br>
<span class=""><br>
> Extensions<br>
><br>
> In addition to generating documentation from comments, a future extension<br>
> would be to automatically generate and insert boilerplate comments into the<br>
> code on demand. As the tool would have access to the AST, it could insert<br>
> comments into the code similar to how tools like clang-tidy and clang-format<br>
> adjust the code. Such generated comments would follow the documentation<br>
> style for comments, and so would generate basic, if not wholly described,<br>
> documentation, including information about parameters, return types, class<br>
> members, etc. For example, the following would be generated for the below<br>
> function:<br>
><br>
><br>
> /// Do Things<br>
><br>
> ///<br>
><br>
> /// TODO: Write detailed description<br>
><br>
> ///<br>
><br>
> /// \param value<br>
><br>
> /// \return int<br>
><br>
> int doThings(int value) { return value; }<br>
><br>
><br>
> In addition, the parsing tool could also be expanded to also parse<br>
> Markdown-style comments, using the Apple Swift Markup style as a reference.<br>
><br>
><br>
> Please let us know if you have comments or concerns about this proposal.<br>
><br>
> Thanks!<br>
><br>
> Julie<br>
</span>Roman<br>
<br>
> ______________________________<wbr>_________________<br>
> cfe-dev mailing list<br>
> <a href="mailto:cfe-dev@lists.llvm.org">cfe-dev@lists.llvm.org</a><br>
> <a href="http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev" rel="noreferrer" target="_blank">http://lists.llvm.org/cgi-bin/<wbr>mailman/listinfo/cfe-dev</a><br>
><br>
</blockquote></div><br></div>