[petsc-dev] Documentation comment support

[Jed Brown]

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/<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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20121223/ed00fd34/attachment.html>