Update Doxygen

[fuchsto]

Everyone (yes, you @dash-project/developers):

• Read the DASH API at https://codedocs.xyz/dash-project/dash/
• Complete it.

[fuchsto]

@devreal Great effort, thank you a lot!

[JosefSchaeffer]

Created a branch sup-106-dash-doxygen for doxygen documentation.

[fuchsto]

@dash-project/developers

IMPORTANT
Currently there is a bug in codedocs which prevents updates of the generated HTML files in browser cache.

To review doxygen output on https://codedocs.xyz/dash-project/dash either

• clear your browser cache (via browser settings, <CTRL>+<F5> does not suffice) or
• use incognito mode (starts with empty cache) (<CTRL>+<SHIFT>+N in chromium`)

[fuchsto]

@dash-project/developers
Examples are now nicely included in Doxygen.
For reference:

• http://dash-api.coreglit.ch/dash-0.3.0 (Doxygen generated on my server)
• https://codedocs.xyz/dash-project/dash/ (automatically generated by codedocs from latest development state)

Please help documenting all examples in dash/examples, just use the \example tag as in dash/examples/ex.02.array/main.cpp.

[fmoessbauer]

@dash-project/developers

Until now, there is not a single commit in sup-106-dash-doxygen. As discussed in the meeting, the documentation will be written in branch doc-106-dash-doxygen to bypass CI.

Please help us to complete the API documentation. Seriously!

[fuchsto]

We use the following style for documentation:

/**
 * Multi-line comment opened with double-star /**.
 * First paragraph is brief description,
 *
 * Paragraphs are separated by empty comment lines. This is
 * the second paragraph and is not included in the brief
 * description.
 */
void wombatify(
   /// Single-line comments opened with *three* forward-slashes.
   /// This is a convenient way to describe function parameters.
   int     num_wombats,
   double  wombat_factor  ///< Postfix-style with <, comment placed *after* described parameter
) {
  // Any comment here is ignored, no matter how it is formatted.
}

[ddiefenthaler]

Thanks for the introduction.

Is /// parameter documentation in any way preferred over \param or @param?

[fuchsto]

@ddiefenthaler Don't use the Java-style @param, please. Apart from that, use whatever you prefer.
I personally like the inline style /// Param description because undocumented parameters are easier to spot.

[fuchsto]

@dash-project/developers

I added a comprehensive style guide for Doxygen documentation in the contributor guide lines:

https://github.com/dash-project/dash/blob/development/CONTRIBUTING.md

Now, don't be shy and give it a try!