View mode: basic / threaded / horizontal-split · Log in · Help
October 16, 2010
Re: automatic code examples in documentation
Interspersed


On 10/15/2010 11:18 AM, Gerrit Wichert wrote:
> This is a post i made deep in the 'improving the join function' thread.
> Steven asked me to open a new thread on it, so here it comes.
>


[ ... ]

> I think its a good idea if the compiler executes a syntax check on the example section,
> like it does on the already implemented syntax checked strings.
>

The perl and parrot guys do this with POD. The pod syntax is simple 
enough that it is trivial to write code that extracts the examples and 
tries to compile them.

I think development of this started because some readers complained 
about book examples not compiling. The obvious (in perl) solution was to 
filter out the examples and verify them as part of a full build.

> Then the compiler part is done with this. This are code examples, not unit tests.
> They are not run with the other unit tests.
> I think code examples are most usefull if they are self-contained little programs.
>
> Part of the document generation may be to compile and run the extracted examples.
> When a example does't compile it can be marked as defunct or excluded from the
> documentation. The doc-generator can catch the output of the running examples
> and add it to the documentation as result.
>
> Shurely there are some problems when trying to compile the examples like wich
> libs to link with, or what about GUI-code, or just code snippets, but for me
> this is all secondary, maybe we can make that work later. The most important part
> is to define the transfer mechanics to get the example code into the documentation.
>
> So what do you think?

Doxygen already supports something like this. Quoting the manual:

http://www.stack.nl/~dimitri/doxygen/commands.html#cmdexample
>
> \example <file-name>
>
> Indicates that a comment block contains documentation for a
> source code example. The name of the source file is <file-name>.
> The text of this file will be included in the documentation, just
> after the documentation contained in the comment block. All examples
> are placed in a list. The source code is scanned for documented
> members and classes. If any are found, the names are cross-referenced
> with the documentation.

The usage example looks like:

/** \example example_test.cpp
 * This is an example of how to use the Test class.
 * More details about the example.
 */

Using this approach would have the benefit of nicely solving the
"how do I compile the examples" question, since the examples become 
stand-alone files with the "usual" compilation semantics. (Doxygen 
supports a search path for this kind of thing, so putting the files
in an examples/ subdirectory is trivial.)

=Austin
Next ›   Last »
1 2
Top | Discussion index | About this forum | D home