[cfe-dev] RFC: clang-doc proposal

[Ansel Sermersheim via cfe-dev]

Julie,

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.

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.

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.

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.

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.

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.

Hope you find some of these comments useful.


On 12/04/2017 12:21 PM, Julie Hockett wrote:
> 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.
>
> 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.
> [snip]
> Please let us know if you have comments or concerns about this proposal.