433206 - Update doxygen.cfg.in

Status: RESOLVED FIXED

(Firefox Build System :: General, defect)

Description

[Joshua Cranmer [:jcranmer]]

Presently, when one runs |make documentation| in the doxygen code, doxygen complains that the configuration file has some deprecated options in it and needs to update. This is the first part of doxygen.cfg.in that I will update.

There are some other minor changes that I'm making, enumerated below:
* Defaulting HAVE_DOT to YES. The dot diagrams are nice to see.
* Modifying EXCLUDE_PREFIXES to clean up the list a lot (like adding nsI so that nsIAbCard is filed under `A' and not `I').
* Letting doxygen comments apply to all in a group. This feature is moderately used in mailnews code at least.

I still need to play around with letting the user decide how to set up EXCLUDE_PREFIXES, but that is currently seeming like too much trouble for so little value.

I am also trying to decide how best to let doxygen handle the undocumented stuff (my current sense is to have it include it as well for completeness's sake).

Comments/questions/concerns/thoughts?

Comment 1

[Joshua Cranmer [:jcranmer]]

Attachment: Updated doxygen.cfg.in

Fixed up the in. Basically, I ran doxygen -u doxygen.cfg.in and tweaked a few parameters for nicer output:
* Modified the IGNORE_PREFIX to better represent the list (basically distribute the interfaces as well)
* A few dot parameters to generate the graphs and keep them somewhat sane
* Add all classes to the list, independent of their documentation level
* Turned off warning for no documentation. That really spams the output

Comment 2

[Christian :Biesinger (don't email me, ping me on IRC)]

Comment on attachment 321414 [details] [diff] [review]
Updated doxygen.cfg.in

-GENERATE_TODOLIST      = YES
+GENERATE_TODOLIST      = NO

why?

Comment 3

[Joshua Cranmer [:jcranmer]]

(In reply to comment #2)
> (From update of attachment 321414 [details] [diff] [review])
> -GENERATE_TODOLIST      = YES
> +GENERATE_TODOLIST      = NO
> 
> why?
> 

(Sorry for the delay)

I changed this because a) no one seemed to use it, and b) I figured that people would be using bugzilla instead for the todo list. If you prefer, I'll change this back to the original setting.

Comment 4

[Christian :Biesinger (don't email me, ping me on IRC)]

XForms uses it...

Comment 5

[Joshua Cranmer [:jcranmer]]

I did not know that; since that is the only problem you have, I will remove it from the final patch before checking in...

Comment 6

[Joshua Cranmer [:jcranmer]]

I've been looking in finer details at doxygen, and have come up with the following points to raise:

* If/when the doxygen parser is fixed to handle xpidl, there is a problem in that nsISupports becomes documented as well, which really impacts dot graphs. See <http://doxygen.db48x.net/mozilla/html/interfacensIMsgFolder__coll__graph.svg> for an example.
* I've not found a way to deal with the, e.g., nsIntSize should be sorting under I but, e.g., nsIObserver should sort under O. Sounds worthwhile enough to feature request, though.
* Macro handling can be better defined, I think. I need to run tests for macro handling.
* The EXCLUDE_PATTERNS looks fragile; some other option may be needed to fix this better.

More, dependent on documentation standards:
* /defgroup, /ingroup (or @ if you prefer) look like they'd be helpful for making documentation better; at that point, adding GROUP_GRAPHS may be helpful.
* Probably nice to document more file headers, but that would probably involve adding a separate documentation command (alldocs, uberdocs?)

I'll hold off on a new patch until I get macros/nsISupports figured out (I've changed the GENERATE_TODOLIST already).

Comment 7

[Daniel Brooks [:db48x]]

(In reply to comment #6)
> * If/when the doxygen parser is fixed to handle xpidl, there is a problem in
> that nsISupports becomes documented as well, which really impacts dot graphs.
> See
> <http://doxygen.db48x.net/mozilla/html/interfacensIMsgFolder__coll__graph.svg>
> for an example.

Yea, it's pretty cool. We could filter nsISupports out of the graphs pretty easily, I think.

> * I've not found a way to deal with the, e.g., nsIntSize should be sorting
> under I but, e.g., nsIObserver should sort under O. Sounds worthwhile enough to
> feature request, though.

I'm not sure there's any way to get this right 100% of the time, short of writing full AI that can read and understand English.

> More, dependent on documentation standards:
> * /defgroup, /ingroup (or @ if you prefer) look like they'd be helpful for
> making documentation better; at that point, adding GROUP_GRAPHS may be helpful.

Yea, making groups for all of the modules would make the docs so much cleaner. We also need to fix the bidi module so that it doesn't use \mainpage.

> * Probably nice to document more file headers, but that would probably involve
> adding a separate documentation command (alldocs, uberdocs?)

Heh, I just run doxygen over the source tree instead of the objdir. See http://doxygen.db48x.net/mozilla-full/html/

Comment 8

[Ben Karel [eschew]]

(In reply to comment #7)
> > * I've not found a way to deal with the, e.g., nsIntSize should be sorting
> > under I but, e.g., nsIObserver should sort under O. Sounds worthwhile enough to
> > feature request, though.
> 
> I'm not sure there's any way to get this right 100% of the time, short of
> writing full AI that can read and understand English.

What sort of cases would a heuristic like "strip 'ns' prefix, plus leading 'I' if followed by another capital letter" get wrong?

Comment 9

[Christian :Biesinger (don't email me, ping me on IRC)]

(In reply to comment #8)
> What sort of cases would a heuristic like "strip 'ns' prefix, plus leading 'I'
> if followed by another capital letter" get wrong?

nsIDNService.cpp

Comment 10

[Daniel Brooks [:db48x]]

(In reply to comment #9)
> (In reply to comment #8)
> > What sort of cases would a heuristic like "strip 'ns' prefix, plus leading 'I'
> > if followed by another capital letter" get wrong?
> 
> nsIDNService.cpp
> 

and nsIOService, and so on.

Comment 11

[Joshua Cranmer [:jcranmer]]

Attachment: Latest patch

Re-requesting r/sr because I've updated significantly from last patch.

Specifically, I've excluded nsCOMPtr_base and nsISupports from documentation because their presence makes the graphs look horrible.

I also enabled preprocessing, which makes it take longer, but, OTOH, makes the documentation more reliable.

This should probably go on both mozilla-central and CVS trunk.

Comment 12

[Benjamin Smedberg]

Comment on attachment 325604 [details] [diff] [review]
Latest patch

I have concerns about the preprocessing: does it use the actual preprocessed sources used by mozilla, or does it preprocess independently? We should ideally either explicitly make .i files or use -save-temps: many defines are set by the makefiles themselves and those wouldn't make it into some doxygen-particular preprocessing step.

Comment 13

[Christian :Biesinger (don't email me, ping me on IRC)]

It uses doxygen's built-in preprocessor, to process the #defines/#ifdefs in the input files. The config file can also specify a list of defines.

As for .i files, I think we only want to process .idl/.h files, which won't work so well with that...

Comment 14

[Benjamin Smedberg]

Comment on attachment 325604 [details] [diff] [review]
Latest patch

Whatever, though I still don't understand why running doxygen on compiler preprocessor output doesn't make sense.

Comment 15

[Joshua Cranmer [:jcranmer]]

A few points:
1. This patch, although based off of the 1.9.0.* sources, will land on 1.9.* trunk if r/sr'd.
2. While doing some tests locally, I discovered that doxygen's preprocessor is dumb and doesn't look through the directories recursively. Including dist/include/xpcom and dist/include/nspr are probably sufficient, however, to trickle down nscore.h and prtypes.h to all files (doxygen will also include any files in the current directory). However, changing this segment would require changing configure.in...
3. One useful thing that using doxygen's preprocessor does is allow us to document #define's.

Comment 16

[Joshua Cranmer [:jcranmer]]

Committed to m-c (with slight change that nsISupports removed from EXCLUDE_SYMBOLS, per biesi's comments over irc):

pushing to ssh://hg.mozilla.org/mozilla-central/
searching for changes
remote: adding changesets
remote: adding manifests
remote: adding file changes
remote: added 1 changesets with 1 changes to 1 files
changeset:   16140:616403a5a73e