<div dir="auto"><div><div class="gmail_extra"><div class="gmail_quote">On Dec 4, 2017 9:21 PM, "Julie Hockett via cfe-dev" <<a href="mailto:cfe-dev@lists.llvm.org">cfe-dev@lists.llvm.org</a>> wrote:<br type="attribution"><blockquote class="quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><span id="m_-3093159149492351458gmail-docs-internal-guid-4ab54f72-232a-73d9-2464-0a2aec30f523"><p style="line-height:1.38;margin-top:0pt;margin-bottom:0pt;text-indent:36pt"><span style="text-indent:36pt;background-color:transparent;font-size:11pt;font-family:Arial;color:rgb(0,0,0);vertical-align:baseline;white-space:pre-wrap">This proposal is to build a new Clang tool for generating C/C++ documentation, similar to other modern documentation generators such as rustdoc</span><span style="text-indent:36pt;background-color:transparent;font-size:11pt;font-family:Arial;color:rgb(0,0,0);vertical-align:baseline;white-space:pre-wrap">.  This tool would be a modular and extensible documentation generator for C/C++ code. It also would introduce a more elegant way of documenting C/C++ code, as well as maintaining backwards-compatibility with Doxygen-style markup to generate documentation.</span><br></p><p dir="ltr" style="line-height:1.38;margin-top:0pt;margin-bottom:0pt;text-indent:36pt"><span style="font-size:11pt;font-family:Arial;color:rgb(0,0,0);background-color:transparent;vertical-align:baseline;white-space:pre-wrap">Today, Doxygen</span><span style="font-size:11pt;font-family:Arial;color:rgb(0,0,0);background-color:transparent;vertical-align:baseline;white-space:pre-wrap"> is a de-facto standard for generating C/C++ documentation. While widely used, the tool itself is a bit cumbersome, its output is both aesthetically and functionally lacking, and the non-permissive license combined with outdated codebase make any improvements difficult. This new tool would aim to simplify the overhead of generating documentation, integrating it into a Clang tool as well as allowing existing comments to continue to be used. It would also allow for relatively easy adaptation to new language features, as it would be built on the Clang parser and would use the Clang AST to generate documentation.</span></p></span></div></blockquote></div></div></div><div dir="auto"><br></div><div dir="auto"><br></div><div dir="auto">I'm currently working on standardese, which aims to do exactly that: <a href="http://github.com/foonathan/standardese">github.com/foonathan/standardese</a></div><div dir="auto"><br></div><div dir="auto"><div class="gmail_extra"><div class="gmail_quote"><blockquote class="quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><span id="m_-3093159149492351458gmail-docs-internal-guid-4ab54f72-232a-73d9-2464-0a2aec30f523"><br><p dir="ltr" style="line-height:1.38;margin-top:0pt;margin-bottom:0pt"><span style="font-size:11pt;font-family:Arial;color:rgb(0,0,0);background-color:transparent;font-weight:700;vertical-align:baseline;white-space:pre-wrap">Proposed Tool</span></p><p dir="ltr" style="line-height:1.38;margin-top:0pt;margin-bottom:0pt;text-indent:36pt"><span style="font-size:11pt;font-family:Arial;color:rgb(0,0,0);background-color:transparent;vertical-align:baseline;white-space:pre-wrap">The proposed tool would consist of two parts. First, it would have a frontend that consumes the Clang-generated AST and generates an intermediate representation of the code and documentation structure, including additional Markdown files. Second, it would have a set of backend modules that consume that representation and output documentation in a particular format (e.g. Markdown, HTML/website, etc.).</span></p></span></div></blockquote></div></div></div><div dir="auto"><br></div><div dir="auto">It is designed in a similar way, but the intermediate format is just in-memory.</div><div dir="auto"><br></div><div dir="auto"><div class="gmail_extra"><div class="gmail_quote"><blockquote class="quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><span id="m_-3093159149492351458gmail-docs-internal-guid-4ab54f72-232a-73d9-2464-0a2aec30f523"><p dir="ltr" style="line-height:1.38;margin-top:0pt;margin-bottom:0pt;text-indent:36pt"><span style="font-size:11pt;font-family:Arial;color:rgb(0,0,0);background-color:transparent;vertical-align:baseline;white-space:pre-wrap">The frontend would be a new tool that uses the Clang parser, which can already parse C/C++ documentation comments (using </span><span style="font-size:11pt;font-family:Inconsolata;color:rgb(0,0,0);background-color:transparent;vertical-align:baseline;white-space:pre-wrap">-</span><span style="font-size:11pt;color:rgb(0,0,0);background-color:transparent;vertical-align:baseline;white-space:pre-wrap"><font face="monospace, monospace">Wdocumentation</font></span><span style="font-size:11pt;font-family:Arial;color:rgb(0,0,0);background-color:transparent;vertical-align:baseline;white-space:pre-wrap"> option). It can be easily used through the LibTooling interface</span><span style="font-size:11pt;font-family:Arial;color:rgb(0,0,0);background-color:transparent;vertical-align:baseline;white-space:pre-wrap">, similarly to other Clang tools such as clang-check or clang-format</span><span style="font-size:11pt;font-family:Arial;color:rgb(0,0,0);background-color:transparent;vertical-align:baseline;white-space:pre-wrap">. The initial steps in this project would be to build this tool using Clang's documentation parser. This tool would be able to attach comments to both functions, types, and macros and resolve declaration references, both of which will be useful in generating effective documentation. Since a good deal of existing C/C++ code uses the Doxygen documentation comment style, which is also supported by Clang's parser (and Doxygen itself can use Clang to parse these comments</span><span style="font-size:11pt;font-family:Arial;color:rgb(0,0,0);background-color:transparent;vertical-align:baseline;white-space:pre-wrap">), this is the syntax we are going to support as well. In the future, we would also like to support Markdown-style comments, akin to Apple Swift Markup</span><span style="font-size:11pt;font-family:Arial;color:rgb(0,0,0);background-color:transparent;vertical-align:baseline;white-space:pre-wrap">. </span></p></span></div></blockquote></div></div></div><div dir="auto">standardese uses libclang (which was a mistake in hindsight), and has its own comment parser as it also supports markup and special commands.</div><div dir="auto"><br></div><div dir="auto"><div class="gmail_extra"><div class="gmail_quote"><blockquote class="quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><span id="m_-3093159149492351458gmail-docs-internal-guid-4ab54f72-232a-73d9-2464-0a2aec30f523"><p dir="ltr" style="line-height:1.38;margin-top:0pt;margin-bottom:0pt;text-indent:36pt"><span style="font-size:11pt;font-family:Arial;color:rgb(0,0,0);background-color:transparent;vertical-align:baseline;white-space:pre-wrap">For implementation, this tool will use the JSON Compilation Database format</span><span style="font-size:11pt;font-family:Arial;color:rgb(0,0,0);background-color:transparent;vertical-align:baseline;white-space:pre-wrap"> to integrate with existing build systems. It would also have subcommands to choose which parts of the code will be documented (e.g. all code, all public signatures, all comment-documented signatures). Once the code is processed, the tool will write out the internal representation of the the documentation in an intermediate representation, encapsulating the necessary information about the code, comments, and structure. This will allow backend tools to take the output and transform it as necessary.</span></p></span></div></blockquote></div></div></div><div dir="auto">This works as described, but the intermediate representation isn't written out.</div><div dir="auto"><br></div><div dir="auto"><div class="gmail_extra"><div class="gmail_quote"><blockquote class="quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><span id="m_-3093159149492351458gmail-docs-internal-guid-4ab54f72-232a-73d9-2464-0a2aec30f523"><p dir="ltr" style="line-height:1.38;margin-top:0pt;margin-bottom:0pt;text-indent:36pt"><span style="font-size:11pt;font-family:Arial;color:rgb(0,0,0);background-color:transparent;vertical-align:baseline;white-space:pre-wrap">The backend modules would cover different possible outputs for the defined intermediate representation. Each module will consume the representation and output documentation in a specific format. Initially, we propose to focus on a module that generates Markdown files, in order to make the first version as simple as possible. Markdown files are automatically rendered on a number of sites and systems, as well as being clear and uncluttered in raw text form. It is also relatively easy to convert Markdown files into other formats, making it a good starting target. An additional module would target HTML/website output.</span></p></span></div></blockquote></div></div></div><div dir="auto"><br></div><div dir="auto">Multiple backends are supported (the new version on develop currently only has XML and HTML though)</div></div>