[cfe-dev] RFC: clang-doc proposal

[Julie Hockett via cfe-dev]

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?

Julie

On Wed, Dec 6, 2017 at 4:21 PM, Ansel Sermersheim via cfe-dev <
cfe-dev at lists.llvm.org> wrote:

> 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.
>>
>
> _______________________________________________
> cfe-dev mailing list
> cfe-dev at lists.llvm.org
> http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20171211/f0fbaec6/attachment.html>