Hi again, some more improvements to the doxygen generation process have been applied:
- Examples are finally filtered now as I specified everything correctly (not a Doxygen shortcoming, bug report closed). > You can also take out the PetscErrorCode ierr; since ierr is never used. > > 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: > http://www.mcs.anl.gov/petsc/petsc-current/src/ksp/ksp/examples/tutorials/ex4.c.html The listing of http://krupp.iue.tuwien.ac.at/petsc-doxygen/ksp_2ksp_2examples_2tutorials_2ex4_8c-example.html 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. - 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. - Private functions no longer show up in the various modules (this was caused by /*MC incorrectly being interpreted as part of a function documentation) 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: http://krupp.iue.tuwien.ac.at/petsc-doxygen/structDM__Plex.html (Note that I could further improve the data field documentation if I were allowed to touch sources and replace /* ... */ by /** ... */) 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)? Best regards, Karli > On Jan 13, 2013, at 5:30 PM, Karl Rupp <rupp at mcs.anl.gov> wrote: > >> Hi, >> >>> Any way to strip the ierr = and CHKERRQ(ierr); from all the html >>> versions of the source code. I find it cluttering and ugly. >> >> 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 >> $> cp -R src/ tmp/ >> $> find tmp/*/examples/tutorials/*.c | xargs sed -i 's/ierr = //g' >> $> find tmp/*/examples/tutorials/*.c | xargs sed -i 's/CHKERRQ(ierr);//g' >> >> This seems to do the job: >> http://krupp.iue.tuwien.ac.at/petsc-doxygen/dm_2examples_2tutorials_2ex1_8c-example.html >> >> >> >> @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? >> >> Best regards, >> Karli >> >> >> >>> >>> On Jan 12, 2013, at 3:10 PM, Karl Rupp <rupp at mcs.anl.gov> wrote: >>> >>>> Dear PETScians, >>>> >>>> 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. >>>> >>>> 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: >>>> http://krupp.iue.tuwien.ac.at/petsc-doxygen/ >>>> To keep the effort for this evaluation reasonable, only the first two >>>> chapters of the user manual are currently migrated. >>>> >>>> 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 >>>> $> doxygen ../src/docs/doxygen/Doxyfile >>>> >>>> Pros: >>>> - Three-way-linking: >>>> >>>> Examples >>>> / \ >>>> Man-Pages -- Manuals >>>> >>>> I injected a minor test case linking an example with a man page and >>>> the developer manual: >>>> http://krupp.iue.tuwien.ac.at/petsc-doxygen/docs_2doxygen_2examples_2ex1_8c-example.html >>>> http://krupp.iue.tuwien.ac.at/petsc-doxygen/ex1_8h_a4204a07ed0f7e0571f0b2b934759b6b0.htm >>>> http://krupp.iue.tuwien.ac.at/petsc-doxygen/dev-minimal-class-standards.html >>>> >>>> - Everything in one place >>>> - Convenient browsing using Tree-View >>>> - Search feature at the top right (yes, it should be 10x larger...) >>>> - BibTeX support >>>> - Just needs simple filters for the existing sources >>>> - Examples, References and 'Referenced by' automatically provided. I >>>> think 'Referenced by' should be turned off, but I kept it for >>>> demonstration purposes. >>>> >>>> >>>> Cons: >>>> - The manuals are converted partly by hand (see discussion below) >>>> - Size: The full output consumes 1GB. Some things can still be turned >>>> off, though. >>>> - 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. >>>> - Group examples: I haven't found a way to group examples, there's only >>>> the list of all examples >>>> - External Dependency rather than 'our own dependency'. >>>> >>>> >>>> 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> ...'. >>>> >>>> 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? ;-) >>>> >>>> Best regards, >>>> Karli >>> >> >
