Getting Involved

Hello,

I am interested in getting involved in the development of clang. I was thinking I liked the sound of the following project from the project list:

Implement an tool to generate code documentation

Could someone suggest a place to start with this? I have just checked out llvm and clang and am about to build them but where should I go from there?

Cheers,

Andrew Lawrence

Hello,

I am interested in getting involved in the development of clang. I was
thinking I liked the sound of the following project from the project list:

*Implement an tool to generate code documentation*

Could someone suggest a place to start with this? I have just checked out
llvm and clang and am about to build them but where should I go from there?

I'd start by looking at the -Wdocumentation warning, which can warn on
malformed doxygen comments. Jump into clang with a debugger and break on
whatever the code is that prints stuff to the console (you could start with
printf/puts/whatever - eventually you're likely to find the code printing
warnings/errors) - then walk up the stack to see where the diagnostics are
emitted, how they're examining the AST to learn about the diagnostic
comments, etc.

With that - then consider looking at Clang's Tooling infrastructure to
write a tool that might do /something/ with the comment pieces from the
AST, etc.

Hi Andy,

I would be happy to answer your questions, help with design and review patches.

This year we had a GSoC proposal for this topic, but, unfortunately,
it was not implemented. Here it is:

Prior Work

* clang already understands doxygen-style comments to a degree and
attaches them to the AST:
http://llvm.org/devmtg/2012-11/Gribenko_CommentParsing.pdf

* doxygen can already use clang as a backend
http://comments.gmane.org/gmane.comp.compilers.clang.devel/29490

* there already is a cldoc https://github.com/jessevdk/cldoc

Project Plan

The project will be split in several stages, each depending on the
previous. A completed stage should be able to stand as a smaller
useful contribution by itself.

Fully parse doxygen comments

* implement comments for macros

* fully parse the doxygen language and produce a complete comment AST

* extend the XML representation of comments to encompass the comment
AST and unresolved references

* resolve links within the translation unit to a Decl* or a USR

Indexing Files

To resolve links across translation units it will be necessary to
retain information from each translation unit.

* define exactly what kind of information should be retained while
indexing the translation unit in order to be able to resolve links
against it

* implement indexing info as side-car files that can be consumed by a tool

Index Database

Depending on how the project progresses it would be possible to design
and implement a

* defining a schema for a DB to store information about possible link targets

* populating DB with information from TUs in the project

Documentation Generator

As a final step the new functionality (CommentAST/XML + indexing files
or indexing database) should be used to implement a simple HTML/LaTeX
documentation generator.

Dmitri

Yes, please implement this. It is extremely necessary, at least for the clang docs.