Hi Jed, > I could only find a manual way: > http://www.stack.nl/~dimitri/__doxygen/manual/commands.html#__cmdexample > <http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdexample> > > > But that is writing "\example someexample.cpp" in the API man page. I > want that link automatically when we _call_ the function from any > example in EXAMPLE_PATH, without messing with the API man page. >
yes, I know that this is not precisely what you wanted. Consequently I added 'It should be possible to inject such \example blocks automatically into source files before creating the documentation...' Further playing with the \example feature showed that it is sufficient to make the examples known to the Doxygen parser once. Hence, all we need to do is to auto-generate a simple header file containing nothing but a description of the examples, e.g. --- file examples.h begin --- /** \example path/to/ex1.c * This is an example of how to use A. */ /** \example path/to/ex2.c * This is an example of how to use B. */ --- file examples.h end --- We can create this automatically with a rather simple shell or Perl script, reusing the description in help[] at the beginning of each example. Then, ex1.c and ex2.c automatically show up as examples in the documentation of A and B. Even better, ex1.c and ex2.c receive anchors to the respective line of the *first use* of A and B. :-) > Thus, Doxygen is presumably the better option over wikis anyway, > even if we ignore the burden of hacking existing wiki systems. > > > This isn't clear to me. Doxygen is all static so even minor doc fixes > necessarily involve a context switch (to find the file in your editor) > and you don't see results immediately. Gollum and Gitit are hosted in a > normal repository so you can work on them offline and use normal tools > for batch processing. Writing a Doxygen input filter to convert [[Some > Wiki Page]] in source code to fully marked up links would be very easy, > so the only "hacking" would be the reverse links (from wiki to API man > page). So I'm not sold either way. The context switch is a point, yes. For the user manual part, the context switch is comparable to manipulating LaTeX files by using dedicated source files for the Doxygen input (i.e. take the current .tex files, strip off some LaTeX specifics, then \include them in Doxygen). This is typically done offline just as updating the reference code comments. A cron script at the webserver can make sure that the doxygen docs are rebuilt every night. In light of the now essentially automatic 'example.h' workaround described above we get the two-way-references for free. Since both the reference and the user manual is built within the same run, we get warnings issued whenever some link becomes invalid. For example, this should minimize documentation errors when renaming functions. I think I'm able to come up with a sample Doxygen documentation of PETSc towards the weekend. Best regards, Karli