[cfe-dev] [PATCH] LibTooling docs

David Röthlisberger david at rothlis.net
Sat Apr 21 06:28:03 PDT 2012


On 19 Apr 2012, at 15:36, Manuel Klimek wrote:
> Please find a first version attached.


The following may be more work and overhead than you had in mind, but here goes:

I am a big fan of *testable* documentation. The easiest way is to generate the documentation from real code (like ClangCheck.cpp or unit tests) that is tested as part of your routine build. Your documentation stays in sync with changes to the code, and the examples in the documentation are guaranteed to work.

Doxygen isn't enough here; I've thrown up a simple proof of concept, inspired by Go's "codewalk" style of documentation, at https://github.com/drothlis/clang-libtooling-docs

https://github.com/drothlis/clang-libtooling-docs/blob/master/LibTooling.html.src#L113
shows a code snippet taken directly from ClangCheck.cpp.
We would need to write additional tests from which to source the remaining code snippets in the document.

https://github.com/drothlis/clang-libtooling-docs/blob/master/LibTooling.html.src#L123
shows a shell command in the documentation that is actually tested as part of the document-generation process.

This highlighted an error in the shell command! See the generated output:
https://github.com/drothlis/clang-libtooling-docs/blob/master/LibTooling.html#L149

Some thoughts on making this work on a large project:

a. The document generation should be run as part of every normal "make all" compilation.

b. The generated document should be checked into source control so that if someone changes ClangCheck.cpp they notice the effect on the documentation in their diffs. I suppose this can get tricky with out-of-source builds -- I'm confident it's doable with gmake but I have no experience with cmake.

c. The document-generation script won't work on Windows unless you have a cygwin-style shell, sed, perl, etc. so maybe the makefile needs to detect when to disable document generation.

Thoughts?
--Dave.





More information about the cfe-dev mailing list