Upgrade doxyfile to doxygen 1.8.8 #5337

Existing options have been kept the same.

For anyone wanting to browse the generated documentation, you can find it @ https://dev.visucore.com/bitcoin/doxygen/index.html @laanwj Noticed your running 1.8.6, maybe you'll want to bump that to 1.8.8?

How do you mean 'regenerate doxyfile'? It's just a configuration file, why would it need regenerating? (github refuses to show me the changes too) I cannot just upgrade doxygen, I use the version provided by my OS.

@laanwj by regenerate doxyfile, I mean I’ve done doxyfile -g, which generates a new default config file, then reapplied our configuration. Our config file now contains all the new doxygen options/docs which have appeared since 1.7.4. I noticed that github doesn’t show the diff, I’m not sure why it wont.

Tested with doxygen 1.8.6. ACK. Generation was error-free.

But the modules section looks quite empty. This is probably because of lack of doxygen compatible comments.

But the modules section looks quite empty. This is probably because of lack of doxygen compatible comments.

That's always been the case.

Looking at the non-comment changes:

-PROJECT_NAME           = Bitcoin
+PROJECT_NAME           = "Bitcoin"
+ALLOW_UNICODE_NAMES    = NO
-ABBREVIATE_BRIEF       = "The $name class" \
-                         "The $name widget" \
-                         "The $name file" \
-                         is \
-                         provides \
-                         specifies \
-                         contains \
-                         represents \
-                         a \
-                         an \
-                         the
+ABBREVIATE_BRIEF       =
+TCL_SUBST              =
+MARKDOWN_SUPPORT       = YES
+AUTOLINK_SUPPORT       = YES
+INLINE_SIMPLE_STRUCTS  = NO
-SYMBOL_CACHE_SIZE      = 0
+LOOKUP_CACHE_SIZE      = 0
-EXTRACT_ALL            = YES
+EXTRACT_ALL            = NO
-EXTRACT_PRIVATE        = YES
+EXTRACT_PRIVATE        = NO
+EXTRACT_PACKAGE        = NO
+SHOW_GROUPED_MEMB_INC  = NO
-SHOW_DIRECTORIES       = NO
+CITE_BIB_FILES         =
-FILE_PATTERNS          = *.c \
-                         *.cc \
-                         *.cxx \
-                         *.cpp \
-                         *.c++ \
-                         *.d \
-                         *.java \
-                         *.ii \
-                         *.ixx \
-                         *.ipp \
-                         *.i++ \
-                         *.inl \
-                         *.h \
-                         *.hh \
-                         *.hxx \
-                         *.hpp \
-                         *.h++ \
-                         *.idl \
-                         *.odl \
-                         *.cs \
-                         *.php \
-                         *.php3 \
-                         *.inc \
-                         *.m \
-                         *.mm \
-                         *.dox \
-                         *.py \
-                         *.f90 \
-                         *.f \
-                         *.for \
-                         *.vhd \
-                         *.vhdl
+FILE_PATTERNS          =
-RECURSIVE              = YES
+RECURSIVE              = NO
+USE_MDFILE_AS_MAINPAGE =
+SOURCE_TOOLTIPS        = YES
+HTML_EXTRA_STYLESHEET  =
-HTML_ALIGN_MEMBERS     = YES
+HTML_DYNAMIC_SECTIONS  = NO
-HTML_DYNAMIC_SECTIONS  = NO
+HTML_INDEX_NUM_ENTRIES = 100
-ENUM_VALUES_PER_LINE   = 4
-USE_INLINE_TREES       = NO
+ENUM_VALUES_PER_LINE   = NO
-MATHJAX_RELPATH        = http://www.mathjax.org/mathjax
+MATHJAX_FORMAT         = HTML-CSS
+MATHJAX_RELPATH        = http://cdn.mathjax.org/mathjax/latest
+MATHJAX_EXTENSIONS     =
+MATHJAX_CODEFILE       =
+EXTERNAL_SEARCH        = NO
+SEARCHENGINE_URL       =
+SEARCHDATA_FILE        = searchdata.xml
+EXTERNAL_SEARCH_ID     =
+EXTRA_SEARCH_MAPPINGS  =
+LATEX_EXTRA_FILES      =
+LATEX_BIB_STYLE        = plain
+MAN_SUBDIR             =
-XML_SCHEMA             = 
+XML_PROGRAMLISTING     = YES
-XML_DTD                = 
+GENERATE_DOCBOOK       = NO
+DOCBOOK_OUTPUT         = docbook
-XML_PROGRAMLISTING     = YES
+DOCBOOK_PROGRAMLISTING = NO
+EXTERNAL_PAGES         = YES
+DIA_PATH               =
+UML_LIMIT_NUM_FIELDS   = 10
+INTERACTIVE_SVG        = NO
+DIAFILE_DIRS           =
+PLANTUML_JAR_PATH      = 

Most changes seem harmless or have to do with new settings in the new version of doxygen.

However: RECURSIVE changed from YES to NO won't that exclude a lot of files? Does it still get the files in /src/script and such?

@laanwj doh. Good catch. Missed that when I was working through. Pushed a fix and verified it's now picking up all files.

Have discovered that running doxygen -u doc/Doxyfile will upgrade the existing file. I've run that and pushed the changes which were slightly different to what I already had here.

I would assume this has rather significant consequences:

-EXTRACT_PRIVATE        = YES
+EXTRACT_PRIVATE        = NO

And:

-ENUM_VALUES_PER_LINE   = 4

This looks better with a value of 1 imho, so that all enums are listed in a list.

Edit:

A few other items to consider, which are probably very dependant on personal taste:

+REFERENCED_BY_RELATION = YES
+REFERENCES_RELATION    = YES

This shows cross-links: "References: xxx", "Referenced by: yyy"

+DOT_IMAGE_FORMAT       = svg
+INTERACTIVE_SVG        = YES

This allows zooming of images. Seems useful for huge class diagrams, but I have the impression it's slower.

+HTML_DYNAMIC_SECTIONS  = YES

This allows to "show" and "hide" class diagrams.

While I'm not yet satisfied with the result, here is how some of this looks like:

http://bitwatch.co/doxygen/mastercore/.../main_8h.html (based on Bitcoin Core 0.9.3) https://dev.visucore.com/bitcoin/doxygen/main_8h.html (OP's original)

The Doxygen file used: https://gist.github.com/dexX7/93e8349b62712a893718 @fanquake: may I ask, if you autogenerate your docs with a script, e.g. "everytime a new commit is merged, regenerate docs"?

You may consider to blank PROJECT_BRIEF to prevent the logo looks to small for the header. (it's more like a workaround though)

@dexX7 Thanks for the feedback. I'll take a look at everything you've posted.

I'm increasingly less convinced that this is desirable.

If you have specific doxygen changes to improve the style or usability, you're very welcome. But a blanket 'update to 1.8.8' that just massages the settings a bit and makes random ancillary changes doesn't seem to be so useful.

Closing this for now; I'm open to improvements in the doxygen configuration, but with rewriting the entire file it's unclear what changes, and why.