<div dir="ltr">Thanks for all the feedback -- we're open to collaboration, so any input or thoughts are welcome! On that note, would anyone be willing to review for this?<div><br></div><div>Julie</div></div><div class="gmail_extra"><br><div class="gmail_quote">On Wed, Dec 6, 2017 at 4:21 PM, Ansel Sermersheim via cfe-dev <span dir="ltr"><<a href="mailto:cfe-dev@lists.llvm.org" target="_blank">cfe-dev@lists.llvm.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Julie,<br>
<br>
This proposal touches on some areas that I know quite well. As a co-founder of the DoxyPress project I have learned a great deal about C++ documentation and I believe I can provide some useful context and experience.<br>
<br>
There are many who believe, inaccurately, that Doxygen supports clang for parsing. This is misleading and not what their "Clang assisted parsing" option does. In reality, Doxygen uses the clang frontend when the Doxygen lex parser gets into an error state while parsing a template declaration. All C++ parsing and lexing is done in a hand written lexer. On the other hand, the clang parsing option in DoxyPress actually does what you would expect, and uses the clang frontend. All documentation is then generated based on the AST.<br>
<br>
I agree, Doxygen was the de facto standard, but it should no longer be considered for documenting modern C++ code since a hand-rolled lexer simply cannot keep up with current syntax. It is worth mentioning the clang documentation generated by DoxyPress is far better than the current Doxygen documentation. If you would like to see it I can post it somewhere for your review.<br>
<br>
If you are looking to add a documentation tool to the clang suite, there are a lot more questions that will come up in the process. If all you are looking to do is document clang itself and clang tooling, that is a much more constrained use case.<br>
<br>
As a side note, the code in clang that supports -Wdocumentation is very limited and only parses a very minimal set of Doxygen/DoxyPress comment syntax. When we looked at it last year, it appeared that a great deal of work would need to be done to support the majority of comments that will be found in an existing C++ codebase which uses Doxygen.<br>
<br>
I would encourage more discussion and a bit more thought on narrowing down the problem you would like to solve. If there are additional questions about how we addressed these issues in DoxyPress we are very happy to be part of the discussion.<br>
<br>
Hope you find some of these comments useful.<span class=""><br>
<br>
<br>
On 12/04/2017 12:21 PM, Julie Hockett wrote:<br>
</span><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">
This proposal is to build a new Clang tool for generating C/C++ documentation, similar to other modern documentation generators such as rustdoc.  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.<br>
<br>
Today, Doxygen 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.<br></span>
[snip]<span class=""><br>
Please let us know if you have comments or concerns about this proposal.<br>
</span></blockquote>
<br><div class="HOEnZb"><div class="h5">
______________________________<wbr>_________________<br>
cfe-dev mailing list<br>
<a href="mailto:cfe-dev@lists.llvm.org" target="_blank">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>
</div></div></blockquote></div><br></div>