[petsc-dev] Documentation comment support

[Barry Smith]

On Jan 7, 2013, at 4:56 PM, Jed Brown <jedbrown at mcs.anl.gov> wrote:

> Karl, do you know a way to make man pages automatically link to use cases in .../examples/tutorials/? (The other direction is fine and dandy, but the reverse links are extremely useful.)

  Jed,

   Do you mean like the Examples section in http://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DMDACreate3d.html? but linking directly to the line that uses the function instead of just to the file?

   Barry

> 
> It could be implemented in an input filter, but that would have to parse the input well enough to know where to insert links to examples.
> 
> 
> On Sun, Dec 23, 2012 at 4:16 PM, Jed Brown <jedbrown at mcs.anl.gov> wrote:
> On Sun, Dec 23, 2012 at 9:56 AM, Karl Rupp <rupp at mcs.anl.gov> wrote:
> Aside from the usual warnings a compiler has to issue if it detects a potentially faulty use of a variable, is there really anything beyond matching comments with the actual variable declarations? The release notes just state:
> 
> 'Clang parses the comments and can detect syntactic and semantic errors in comments.'
> 
> So even though in principle it *could* do all the nice traces and such, I doubt that developers will make clang an all-in-one-suite-for-everything including a documentation generator, because this monolithic thingy is exactly what they complain about in GCC.
> 
> Sure, but they already have a features like "this is uninitialized" that trace through function calls. If someone passes in a real *foo as @param[out], but the function itself depends on the value of foo[0], that should be a documentation warning. I.e., some system should be able to generate that warning. Meanwhile, it's most convenient for the compiler to be the unified front-end to all warnings about your code. The main reasons are
> 
> * configuration: only the compiler is guaranteed to see the right paths and have the right macros defined
> * interface: we run the compiler frequently and it's integrated into our workflows
>  
> 
> As for the cross-referencing manuals and man-pages: I talked with Barry about that two weeks ago, since I had to produce a HTML version of my PhD thesis:
>   http://www.iue.tuwien.ac.at/phd/rupp/
> I used tex4ht, which is still not perfect, but worked with reasonable effort. At least one can get reasonable HTML output from LaTeX.
> Maybe one could customize the anchors so that one can not only reference out of the HTML output, but also *into* the output - however, I still have to check that...
> 
> I think that is the most important part. I would love for the DMDACreate2d man page to have a link into that section of the manual, for example. PETSc's manual already has links running the other direction.
>  
> About two years ago I went through the deal.II documentation generator, at that time it used quite a number of scripts in order to extract the necessary information from the files. These were required to overcome some of the deficiencies of Doxygen at that time, e.g. math fonts and I think some cross-links. Meanwhile Doxygen also supports math formulae, and a couple of additional structuring mechanisms. I haven't tried any of the three items you mentioned, though...
> 
> Yeah, I see some hackery in doc/doxygen/tutorial/Makefile.
> 
> I might experiment with doxygen filters in a young project to see if it can be coerced into doing the things we'd like.
>