[cfe-dev] libclang based non-doxygen/javadoc-style tool

[Michael Lehn]

Hi,                                                                              
                                                                                 
libclang is really a great tool for writing your own documentation tool.  I
never liked the concept of javadoc/doxygen of putting all the documentation
into the header/source files.  In my opinion it bloats the headers and makes
them unclear.  What I always wanted is a non-invasive documentation tool that
leaves my code clean.  Fortunately libclang gives me the choice to do it my
way:

My libclang based tool extracts all the declarations I am interested to comment
and creates a doc-file with stubs:
  (1a) http://www.mathematik.uni-ulm.de/~lehn/FLENS/flens/matrixtypes/symmetric/impl/symatrix.doc.txt
This can be converted to HTML:
  (1b) http://www.mathematik.uni-ulm.de/~lehn/FLENS/flens/matrixtypes/symmetric/impl/symatrix.html
The tool also keeps these code snippets in sync with the header/source files.
E.g. it adds stubs new methods, modifies stubs if the header/source changes,...

For sure, you want to add some useful comments to the stubs, e.g.
  (2a) http://www.mathematik.uni-ulm.de/~lehn/FLENS/flens/matrixtypes/general/impl/gematrix.doc.txt
and you get some nicer output:
  (2b) http://www.mathematik.uni-ulm.de/~lehn/FLENS/flens/matrixtypes/general/impl/gematrix.html
Another example
  (2c) http://www.mathematik.uni-ulm.de/~lehn/FLENS/flens/lapack/impl/sv.doc.txt
  (2d) http://www.mathematik.uni-ulm.de/~lehn/FLENS/flens/lapack/impl/sv.html

Well, you still have to write the documenting text yourself (and I did not write
much so far) but you see that some reStructuredText can be used.  Here a page with
tables, list, footnotes, links and tables with list:
  (3a) http://www.mathematik.uni-ulm.de/~lehn/FLENS/flens/lapack/lapack.doc.txt
  (3b) http://www.mathematik.uni-ulm.de/~lehn/FLENS/flens/lapack/lapack.html

Another nice feature is about creating tutorials.  Assume you have written a
small example for your project.  Then you want to write some general notes, show
the source code, comment the source code, tell people how to compile it and show
its output:
  (4a) http://www.mathematik.uni-ulm.de/~lehn/FLENS/flens/examples/lapack-gelsy.doc.txt
When this  doc-file gets converted to HTML it will include the example source file,
compile it and execute it:
  (4b) http://www.mathematik.uni-ulm.de/~lehn/FLENS/flens/examples/lapack-gelsy.html

The certainly coolest feature that libclang gives to all of us is cross referencing
the source code, e.g.
  (5) http://www.mathematik.uni-ulm.de/~lehn/FLENS/flens/examples/lapack-gelsy.cc.html
Note the words in the source code that are (dotted) underlined.  For overloaded functions
you get red underlined word, e.g. 'cxxbla::ger':
  (6) http://www.mathematik.uni-ulm.de/~lehn/FLENS/flens/blas/level2/r.tcc.html#60

I was really surprised how easy libclang makes it to implement such tools!


Michael