Opened 3 years ago

Closed 2 years ago

#13107 closed Patch - Bug Fix (fixed)

Clean up almost all doxygen warnings.

Reported by: David Hampton <mythtv@…> Owned by: Stuart Auchterlonie
Priority: minor Milestone: 30.0
Component: MythTV - General Version: Master Head
Severity: medium Keywords:
Cc: Ticket locked: no


1) Update the base configuration file to doxygen 1.8.13.

2) Tweak the configuration file to:

a) Use the LOOKUP_CACHE_SIZE recommended by doxygen. b) Fix up the exclude paths patterns. c) Increase the number of nodes in a graph, and use the default system font.

3) Update the main architecture document to eliminate warnings. Add a couple of new groups for the libraries for later documentation. Remove some unintentional links. Remove the Transcoding Daemon documentation.

4) Fix doxygen complaints about macros before the keyword 'public'. Doxygen gets easily confused, and unless the token before 'public' is a semicolon, it doesn't recognize the keyword

5) Fix doxygen warning in all the source files.

a) Function parameter names must be the same across function declaration, function declaration, and doxygen comment declaration. If the function is inherited from a parent class and has no documentation of its own, then the names must also match those of the parent class function.

b) Remove parameter documentation if parameters have been removed.

c) Add parameter documentation if parameters have been added.

d) Fix punctuation in comments that causes a doxygen warning, or makes doxygen think that a link should be created.

e) Fix doxygen commands to be acceptable (wrong case, wrong command, etc). Convert parameter arguments from javadoc style (@my_var) to doxygen style (\param my_var).

f) If a doxygen comment immediately precedes or follows the function definition or declaration, then the doxygen function declaration is redundant. Typically it just ends up causing problems because its argument list (types and names) must be kept in sync with those of both the definition (and declaration if separate). If it isn't kept in sync, doxygen's simple parser will complain that it can't find a matching function for the comment.

Change History (3)

comment:1 Changed 3 years ago by David Hampton <mythtv@…>

comment:2 Changed 3 years ago by Stuart Auchterlonie

Milestone: needs_triage30.0
Owner: set to Stuart Auchterlonie
Status: newassigned

I'll need to upgrade the infrastructure to doxygen 1.8.13 before the config change part of this can be merged

comment:3 Changed 2 years ago by David Hampton <mythtv@…>

Resolution: fixed
Status: assignedclosed

In 14486bc8553fbc96dc3b6e90a5e061764ef62654/mythtv:

Merge the 'devel/dh/doccleanup' branch into master.

The majority of these changes are to the documentation itself, either
adding documentation or correcting nits that throw off the doxygen
parser. There are a couple of places where variable names were
changed to match up declaration and definition and code. This patch
also adds semicolons after a number of macro calls. While not needed
by the compiler, the lack of a semicolon completely throws off the
doxygen parser. Upgrade the doxygen configuration file to the latest
version. Fixes #13107.

Note: See TracTickets for help on using tickets.