[mythtv-commits] Ticket #13107: Clean up almost all doxygen warnings.

MythTV noreply at mythtv.org
Fri Aug 18 23:52:21 UTC 2017


#13107: Clean up almost all doxygen warnings.
------------------------------------------+--------------------------
     Reporter:  David Hampton <mythtv@…>  |      Owner:
         Type:  Patch - Bug Fix           |     Status:  new
     Priority:  minor                     |  Milestone:  needs_triage
    Component:  MythTV - General          |    Version:  Master Head
     Severity:  medium                    |   Keywords:
Ticket locked:  0                         |
------------------------------------------+--------------------------
 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.

--
Ticket URL: <https://code.mythtv.org/trac/ticket/13107>
MythTV <http://www.mythtv.org>
MythTV Media Center


More information about the mythtv-commits mailing list