<div dir="ltr">On Tue, Jan 15, 2013 at 2:15 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 again,<br>
<br>
some more improvements to the doxygen generation process have been applied:<br></blockquote><div><br></div><div style>Right now, the search stinks. If I type in</div><div style><br></div><div style> GetCone</div><div style>
<br></div><div style>I get nothing found, whereas</div><div style><br></div><div style> DMPlexGetCone</div><div style><br></div><div style>has three things found, but does not find DMPlexSetCone. This is crappy, and will</div>
<div style>not replace seeing everything on one page, which I miss.</div><div style><br></div><div style> Matt</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
- Examples are finally filtered now as I specified everything correctly (not a Doxygen shortcoming, bug report closed).<div class="im"><br>
<br>
<br>
> You can also take out the PetscErrorCode ierr; since ierr is never used.<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
Note that your change now changes the line numbers because it removes some lines, thus the lines do not match up with the C code. In our current way of processing we list the line numbers on the left side: <a href="http://www.mcs.anl.gov/petsc/petsc-current/src/ksp/ksp/examples/tutorials/ex4.c.html" target="_blank">http://www.mcs.anl.gov/petsc/<u></u>petsc-current/src/ksp/ksp/<u></u>examples/tutorials/ex4.c.html</a><br>
</blockquote>
<br></div>
The listing of<br>
<a href="http://krupp.iue.tuwien.ac.at/petsc-doxygen/ksp_2ksp_2examples_2tutorials_2ex4_8c-example.html" target="_blank">http://krupp.iue.tuwien.ac.at/<u></u>petsc-doxygen/ksp_2ksp_<u></u>2examples_2tutorials_2ex4_8c-<u></u>example.html</a><br>
is now identical with the one Barry mentioned - except for a violation of coding style on lines 49/50 that already affects the sources. I'll send a separate email on that.<br>
<br>
- Examples now carry correct line numbers even with things stripped out. This required a small Doxygen patch, which I've sent to the developers for inclusion in the next release.<br>
<br>
- Private functions no longer show up in the various modules (this was caused by /*MC incorrectly being interpreted as part of a function documentation)<br>
<br>
There are still a bunch of private data structures shown. There is no consistent way of determining whether a data structure is private or not. The underscore could be a criterion, but then it misses some rather important things such as DM_Plex:<br>
<a href="http://krupp.iue.tuwien.ac.at/petsc-doxygen/structDM__Plex.html" target="_blank">http://krupp.iue.tuwien.ac.at/<u></u>petsc-doxygen/structDM__Plex.<u></u>html</a><br>
(Note that I could further improve the data field documentation if I were allowed to touch sources and replace /* ... */ by /** ... */)<br>
<br>
Has there already been a decision made on whether the Doxygen documentation should be kept for the future (irrespective of whether this has any influence on the use of sowing)?<div class="HOEnZb"><div class="h5"><br>
<br>
Best regards,<br>
Karli<br>
<br>
<br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
On Jan 13, 2013, at 5:30 PM, Karl Rupp <<a href="mailto:rupp@mcs.anl.gov" target="_blank">rupp@mcs.anl.gov</a>> wrote:<br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Hi,<br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Any way to strip the ierr = and CHKERRQ(ierr); from all the html versions of the source code. I find it cluttering and ugly.<br>
</blockquote>
<br>
It doesn't work 'directly' as Doxygen currently does not apply filters to examples. The remedy is an additional copy&conversion step, i.e. something comparable to<br>
$> cp -R src/ tmp/<br>
$> find tmp/*/examples/tutorials/*.c | xargs sed -i 's/ierr = //g'<br>
$> find tmp/*/examples/tutorials/*.c | xargs sed -i 's/CHKERRQ(ierr);//g'<br>
<br>
This seems to do the job:<br>
<a href="http://krupp.iue.tuwien.ac.at/petsc-doxygen/dm_2examples_2tutorials_2ex1_8c-example.html" target="_blank">http://krupp.iue.tuwien.ac.at/<u></u>petsc-doxygen/dm_2examples_<u></u>2tutorials_2ex1_8c-example.<u></u>html</a><br>
<br>
<br>
<br>
@Jed: I've disabled the EXTRACT_ALL switch, now only documentation for commented entities is generated. Static functions should not be shown anyway (EXTRACT_PRIVATE = NO). I could also set EXCLUDE_PATTERN to something like *_Private and/or *_Internal. Do you know a better systematic way of identifying internal stuff without touching sources?<br>
<br>
Best regards,<br>
Karli<br>
<br>
<br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
On Jan 12, 2013, at 3:10 PM, Karl Rupp <<a href="mailto:rupp@mcs.anl.gov" target="_blank">rupp@mcs.anl.gov</a>> wrote:<br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Dear PETScians,<br>
<br>
as indicated in a previous thread, I spent some time on investigating what Doxygen can do for us (thanks to Peter for some pointers). I set myself the constraint of not touching any existing sources in order to keep the generation of FORTRAN stubs intact.<br>
<br>
Actually, it turns out that even under this harsh constraints, Doxygen produces good results. Particularly the dynamic tree-view and the search feature are very nice. Have a look here:<br>
<a href="http://krupp.iue.tuwien.ac.at/petsc-doxygen/" target="_blank">http://krupp.iue.tuwien.ac.at/<u></u>petsc-doxygen/</a><br>
To keep the effort for this evaluation reasonable, only the first two chapters of the user manual are currently migrated.<br>
<br>
The doxygen run is not integrated in any makefiles. One needs to run doxygen (version 1.8.0 or higher) from petsc-dev/doc by<br>
$> doxygen ../src/docs/doxygen/Doxyfile<br>
<br>
Pros:<br>
- Three-way-linking:<br>
<br>
Examples<br>
/ \<br>
Man-Pages -- Manuals<br>
<br>
I injected a minor test case linking an example with a man page and the developer manual:<br>
<a href="http://krupp.iue.tuwien.ac.at/petsc-doxygen/docs_2doxygen_2examples_2ex1_8c-example.html" target="_blank">http://krupp.iue.tuwien.ac.at/<u></u>petsc-doxygen/docs_2doxygen_<u></u>2examples_2ex1_8c-example.html</a><br>
<a href="http://krupp.iue.tuwien.ac.at/petsc-doxygen/ex1_8h_a4204a07ed0f7e0571f0b2b934759b6b0.htm" target="_blank">http://krupp.iue.tuwien.ac.at/<u></u>petsc-doxygen/ex1_8h_<u></u>a4204a07ed0f7e0571f0b2b934759b<u></u>6b0.htm</a><br>
<a href="http://krupp.iue.tuwien.ac.at/petsc-doxygen/dev-minimal-class-standards.html" target="_blank">http://krupp.iue.tuwien.ac.at/<u></u>petsc-doxygen/dev-minimal-<u></u>class-standards.html</a><br>
<br>
- Everything in one place<br>
- Convenient browsing using Tree-View<br>
- Search feature at the top right (yes, it should be 10x larger...)<br>
- BibTeX support<br>
- Just needs simple filters for the existing sources<br>
- Examples, References and 'Referenced by' automatically provided. I think 'Referenced by' should be turned off, but I kept it for demonstration purposes.<br>
<br>
<br>
Cons:<br>
- The manuals are converted partly by hand (see discussion below)<br>
- Size: The full output consumes 1GB. Some things can still be turned off, though.<br>
- Link names: The URLs for the man pages contain some hash rather than the function name. Former versions of Doxygen used to have the full function name in the URL, similar to what sowing produces.<br>
- Group examples: I haven't found a way to group examples, there's only the list of all examples<br>
- External Dependency rather than 'our own dependency'.<br>
<br>
<br>
The most time consuming part was/is the migration of the manuals. This is partly a technical thing (Doxygen does not parse all LaTeX stuff, so this needs to be filtered), but also a semantic thing. For example, in a PDF you naturally refer to another Chapter by something like 'as we know from Chapter 1 ...', while in an HTML document it is preferable to have something like 'as we know from <a>the introductory discussion</a> ...'.<br>
<br>
Doxygen allows to have commands for switching between different output targets, so in principle it would be possible to transfer the current manuals to a markup-time format, which can then be used with doxygen as well as for dedicated standalone PDFs as we have it now. For that to happen it is essential to come to a conclusion on whether we want to use Doxygen in the future, or whether we want to stick with the current tools. Barry? ;-)<br>
<br>
Best regards,<br>
Karli<br>
</blockquote>
<br>
</blockquote>
<br>
</blockquote>
<br>
</blockquote>
<br>
</div></div></blockquote></div><br><br clear="all"><div><br></div>-- <br>What most experimenters take for granted before they begin their experiments is infinitely more interesting than any results to which their experiments lead.<br>
-- Norbert Wiener
</div></div>