[cfe-dev] [GSoC] Doxygen documentation with clang

[Philipp Möller]

"Jonathan 'Rynn' Sauer" <jonathan.sauer at gmx.de>
writes:

> Hello,
>
>> one of the project ideas for GSoC 2014 is a clang-based tool to
>> generate documentation using doxygen-style comments in the source
>> code.  I wanted to gauge the interest into such a project, see if
>> someone is willing to mentor it, and provide a rough outline of what
>> my idea of the project is. Any feedback on this is very welcome.
>
> This project sounds very interesting and definitely useful;
> "clang-doc" in addition to clang-format and the static analyzer.
>
> A few points:
>
> 1. Doxygen offers the possibility to define custom commands in its
>    config file[1]. I am using this in my code to document the bindings to
>    the scripting language Lua, i.e.  @luaparam to document a parameter
>    and @luareturn to document a return value. AFAIK clang currently does
>    not support custom commands and warns about their use (unless
>    -Wno-documentation-unknown-command is specified).
>
>    Do you plan on extending clang so custom doxygen commands can be
>    defined?

Yes, that would certainly be necessary. I would go so far to say, that
it is necessary to support custom commands in "clang-doc" (tentative
name for now).

If custom commands are supported they would be defined in the
documentation generation file similar to Doxygen and the comment parser
would also handle their expansion. Additionally they could be passed as
command line parameters so -Wdocumentation-unknown-command can be used
during normal compilation.

See Dmitri's reply for a possible trick to get this working now.

>
>
> 2. As far as the external projects you mention go: Maybe they could be
>    implemented with precompiled header files, similar to the way clang's
>    modules (in C and Objective-C) are handled[2]: By saving and loading
>    clang's AST.

Interesting approach, but Module support is experimental for C++ and
likely to change should they ever be standardized. I'm a little out of
the loop concerning the C++ modules proposal and unable to find
up-to-date information. (AFAIK, SG2 hasn't done any work on the proposal
during the last meetings.) Maybe someone more familiar with modules
could provide some insight if this is feasible.

>
> [1] <http://www.stack.nl/~dimitri/doxygen/manual/custcmd.html>
> [2] <http://clang.llvm.org/docs/Modules.html>