<div dir="ltr">On Tue, Jan 8, 2013 at 1:35 PM, Karl Rupp <span dir="ltr"><<a href="mailto:rupp@mcs.anl.gov" target="_blank">rupp@mcs.anl.gov</a>></span> wrote:<br><div class="gmail_extra"><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Hi Jed,<div class="im"><br>
<br>
> I could only find a manual way:<br>
</div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<a href="http://www.stack.nl/~dimitri/__doxygen/manual/commands.html#__cmdexample" target="_blank">http://www.stack.nl/~dimitri/_<u></u>_doxygen/manual/commands.html#<u></u>__cmdexample</a><div class="im"><br>
<<a href="http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdexample" target="_blank">http://www.stack.nl/~dimitri/<u></u>doxygen/manual/commands.html#<u></u>cmdexample</a>><br>
<br>
<br>
But that is writing "\example someexample.cpp" in the API man page. I<br>
want that link automatically when we _call_ the function from any<br>
example in EXAMPLE_PATH, without messing with the API man page.<br>
<br>
</div></blockquote>
<br>
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...'<br>
<br>
Further playing with the<br>
\example<br>
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.<br>
<br>
--- file examples.h begin ---<br>
<br>
/** \example path/to/ex1.c<br>
* This is an example of how to use A.<br>
*/<br></blockquote><div><br></div><div style>Presumably this can be a list of A01 to A99?</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
/** \example path/to/ex2.c<br>
* This is an example of how to use B.<br>
*/<br>
<br>
--- file examples.h end ---<br>
<br>
We can create this automatically with a rather simple shell or Perl script, reusing the description in help[] at the beginning of each example.<br></blockquote><div><br></div><div style>It's more than that. There are examples that use MatSetValuesBlockedLocal(), for example, but their primar y purpose is something else. We'd like them to be linked automatically. Distinguishing "dedicated" examples (whose sole purpose is demonstrating that interface) might be cool, but most interfaces won't have a dedicated example.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
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. :-)</blockquote><div><br></div><div style>
Cool.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="im"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
This isn't clear to me. Doxygen is all static so even minor doc fixes<br>
necessarily involve a context switch (to find the file in your editor)<br>
and you don't see results immediately. Gollum and Gitit are hosted in a<br>
normal repository so you can work on them offline and use normal tools<br>
for batch processing. Writing a Doxygen input filter to convert [[Some<br>
Wiki Page]] in source code to fully marked up links would be very easy,<br>
so the only "hacking" would be the reverse links (from wiki to API man<br>
page). So I'm not sold either way.<br>
</blockquote>
<br></div>
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.<br>
<br>
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.<br>
<br>
I think I'm able to come up with a sample Doxygen documentation of PETSc towards the weekend.<br></blockquote><div><br></div><div style>Cool, I look forward to seeing it. Initially, it'll be best to write an input filter that reformats sowing comments into Doxygen comments (and perhaps inserts other stuff). If we like the result, we could apply the change everywhere, but we'll need to also update Fortran stub handling before we can leave sowing format in the source tree.</div>
</div></div></div>