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>
