540381 - update doxygen.cfg

Status: RESOLVED WONTFIX

(Firefox Build System :: General, defect)

Description

[Daniel Brooks [:db48x]]

There have been a few releases of doxygen since the file in the repository was created, so it throws a few warnings about depreciated options.

Additionally, doxygen gets into an infinite loop of some kind with the current configuration. It seems to happen whenever the one of the include directories is the same as or is included by one of the input directories. Currently, we pass ./dist/include as both an input and an include directory, making it impossible to generate the documentation out of the box with a recent doxygen.

I also turned on a few other doxygen options seem like nice ideas, such as the search box.

Comment 1

[Daniel Brooks [:db48x]]

Attachment: bug540381-1.diff

Comment 2

[Joshua Cranmer [:jcranmer]]

Comment on attachment 422177 [details] [diff] [review]
bug540381-1.diff

A diff -W would have been better...

Trimming to only take into account the changes that are noteworthy:

>+IDL_PROPERTY_SUPPORT   = YES

This looks pointless, but it's the default, I guess

>+SYMBOL_CACHE_SIZE      = 2

Hmm... do we fall under the category of "the default is not good for us"?

>-WARN_IF_UNDOCUMENTED   = NO
>+WARN_IF_UNDOCUMENTED   = YES
>-WARN_NO_PARAMDOC       = NO
>+WARN_NO_PARAMDOC       = YES
>-WARN_LOGFILE           = 
>+WARN_LOGFILE           = @MOZ_DOC_WARNING_LOG@

Well... that should reduce the spamming log syndrome. On the other hand, I think that the doxygen undocumented warnings are going to be mostly useless if we don't get people fixing these problems. Blaming people for new warnings introductions would probably be very helpful.

>+HTML_DYNAMIC_SECTIONS  = YES

I would personally argue that these make the output files harder to read. Then again, I do like staring at all the pretty pictures in some of their beautiful complexities.

>-GENERATE_TREEVIEW      = NO
>+GENERATE_TREEVIEW      = YES

The treeview eats up pretty much an entire column; with 5 columns already overflowing the page width on my laptop, it makes navigation more difficult. Therefore, could you bump that value down to 4?

>+USE_INLINE_TREES       = YES

Wow, that really helps!

>+SEARCHENGINE           = YES

The search engine isn't terribly helpful for mozilla, I think for the following reasons:
1. It's slow (there's probably several thousand items that it's trying to index)
2. We have MXR. And MDC. And DXR (although the latter is still in development). Granted, these won't take you to prettified cross-linked documentation (DXR might be able to do that eventually, though), but it generally takes you to something passable.
3. It appears it can only search at the beginning of a symbol, so it makes it not fun to try to find stuff like "what was that variant thing called again?"

>diff -r 6ea1b12adda1 -r 8ff500a4d187 configure.in
>--- a/configure.in	Mon Jan 18 00:39:46 2010 -0500
>+++ b/configure.in	Mon Jan 18 02:12:42 2010 -0600
>@@ -7098,7 +7098,7 @@
> AC_SUBST(MOZ_DOC_INPUT_DIRS)
> 
> dnl Use commas to specify multiple dirs to this arg
>-MOZ_DOC_INCLUDE_DIRS='./dist/include ./dist/include/nspr'
>+MOZ_DOC_INCLUDE_DIRS=
> MOZ_ARG_WITH_STRING(doc-include-dirs,
> [  --with-doc-include-dirs=DIRS  
>                           Include dirs to preprocess doc headers],

Why remove the default value?

I think the "./dist/include/nspr" can go away due to the flattening of dist/include, but I am not fully certain on that part. Now if only comm-central could get rid of REQUIRES...

I also wish there were something to do about the five or so @mainpages we have, none of which is a mainpage for all of m-c or c-c code.

Comment 3

[Daniel Brooks [:db48x]]

(In reply to comment #2)
> (From update of attachment 422177 [details] [diff] [review])
> A diff -W would have been better...

Indeed. My apologies.

> 
> >+SYMBOL_CACHE_SIZE      = 2
> 
> Hmm... do we fall under the category of "the default is not good for us"?

You know, I had intended to time it and see, but although I timed each run, I completely forgot to actually record any times once I actually got everything working properly. I suspect, however, that the default value is more than adequate.

> 
> >-WARN_IF_UNDOCUMENTED   = NO
> >+WARN_IF_UNDOCUMENTED   = YES
> >-WARN_NO_PARAMDOC       = NO
> >+WARN_NO_PARAMDOC       = YES
> >-WARN_LOGFILE           = 
> >+WARN_LOGFILE           = @MOZ_DOC_WARNING_LOG@
> 
> Well... that should reduce the spamming log syndrome. On the other hand, I
> think that the doxygen undocumented warnings are going to be mostly useless if
> we don't get people fixing these problems. Blaming people for new warnings
> introductions would probably be very helpful.

One step at a time. http://doxygen.db48x.net/mozilla/doxygen-warnings.log

> >+HTML_DYNAMIC_SECTIONS  = YES
> 
> I would personally argue that these make the output files harder to read. Then
> again, I do like staring at all the pretty pictures in some of their beautiful
> complexities.

Yes, I love the graphs too, but since we don't need them every time we see the page and some of them are quite large...

> 
> >-GENERATE_TREEVIEW      = NO
> >+GENERATE_TREEVIEW      = YES
> 
> The treeview eats up pretty much an entire column; with 5 columns already
> overflowing the page width on my laptop, it makes navigation more difficult.
> Therefore, could you bump that value down to 4?

Certainly.

> 
> >+USE_INLINE_TREES       = YES
> 
> Wow, that really helps!
> 
> >+SEARCHENGINE           = YES
> 
> The search engine isn't terribly helpful for mozilla, I think for the following
> reasons:
> 1. It's slow (there's probably several thousand items that it's trying to
> index)
> 2. We have MXR. And MDC. And DXR (although the latter is still in development).
> Granted, these won't take you to prettified cross-linked documentation (DXR
> might be able to do that eventually, though), but it generally takes you to
> something passable.
> 3. It appears it can only search at the beginning of a symbol, so it makes it
> not fun to try to find stuff like "what was that variant thing called again?"

Yes, it's a bit dissapointing on the one hand, but I was surprised that it worked at all. Since it's entirely client-side, I expected to see slow-script dialogs :)

> 
> >diff -r 6ea1b12adda1 -r 8ff500a4d187 configure.in
> >--- a/configure.in	Mon Jan 18 00:39:46 2010 -0500
> >+++ b/configure.in	Mon Jan 18 02:12:42 2010 -0600
> >@@ -7098,7 +7098,7 @@
> > AC_SUBST(MOZ_DOC_INPUT_DIRS)
> > 
> > dnl Use commas to specify multiple dirs to this arg
> >-MOZ_DOC_INCLUDE_DIRS='./dist/include ./dist/include/nspr'
> >+MOZ_DOC_INCLUDE_DIRS=
> > MOZ_ARG_WITH_STRING(doc-include-dirs,
> > [  --with-doc-include-dirs=DIRS  
> >                           Include dirs to preprocess doc headers],
> 
> Why remove the default value?

As I said, the default values result in a hang since ./dist/include is also an input directory.

> I also wish there were something to do about the five or so @mainpages we have,
> none of which is a mainpage for all of m-c or c-c code.

Yes, I laugh every time I see the index page :)

Comment 4

[Joshua Cranmer [:jcranmer]]

Comment on attachment 422177 [details] [diff] [review]
bug540381-1.diff

Belated r+ modulo my later comments, although we probably need another update for more doxygen changes.

Comment 5

[Nicolas Silva [:nical]]

I tried the patch in attachment 422177 [details] [diff] [review] and it produces the following error when I try to build:

In general, the files in '/home/nico/Dev/mozilla/mozilla-
central/js/src/config' should always be exact copies of originals in
'/home/nico/Dev/mozilla/mozilla-central/config'.  A change made to one
should also be made to the other.  See 'check-sync-dirs.py' for more
details.
make[1]: *** [check-sync-dirs-config] Error 1
make: *** [build] Error 2

Comment 6

[(not currently active) Ted Mielczarek]

The changes to config/rules.mk need to be applied to js/src/config/rules.mk as well. You can simply cp config/rules.mk js/src/config/rules.mk in your tree to make that error go away.

Comment 7

[Nick Alexander :nalexander [he/him]]

Closing in favour of Bug 1435424, which tracks removing Doxygen from the build system entirely.