Opened 4 years ago

Closed 4 years ago

#4234 closed defect (fixed)

Remove doxygen warnings prior to 1.0 release

Reported by: marcin Owned by: fdupont
Priority: medium Milestone: Kea1.0
Component: documentation Version: git
Keywords: Cc:
CVSS Scoring: Parent Tickets:
Sensitive: no Defect Severity: Low
Sub-Project: DHCP Feature Depending on Ticket:
Estimated Difficulty: 0 Add Hours to Ticket: 0
Total Hours: 0 Internal?: no

Description

Since 0.9.2 the number of doxygen warnings grew. We should take a look at current warnings and remove those that can be easily removed. The problematic ones may be those emanating from the old BIND10 dns code. Those we'd probably leave alone.

I open this ticket per Kea call on 12/09/2015.

Subtickets

Change History (10)

comment:1 Changed 4 years ago by fdupont

  • Owner set to fdupont
  • Status changed from new to accepted

comment:2 Changed 4 years ago by fdupont

Created a trac4234 branch. You can use it, just warn before and after here...

comment:3 Changed 4 years ago by fdupont

  • Owner changed from fdupont to UnAssigned
  • Status changed from accepted to assigned

Gave up for remaining warnings (note lib/eval and lib/dns warnings won't be fixed and they are more than the half).
Please remove more warnings and put the ticket on the review queue.

comment:4 Changed 4 years ago by fdupont

Summary of problems I don't know (yet) how to solve in a reasonable way:

  • isc::asiolink::isc::asiolink spurious name space
  • io_socket.h not found includes
  • doxygen forgot the Lease:: for the Type argument of Lease6 constructor
  • UnixCommandSocket? is local so can't be referenced from command-socket.dox (a fix could require a major code change)

comment:5 Changed 4 years ago by fdupont

  • Status changed from assigned to reviewing

Fixed all issues. Ready for review.

comment:6 Changed 4 years ago by marcin

  • Owner changed from UnAssigned to marcin

comment:7 follow-up: Changed 4 years ago by marcin

  • Owner changed from marcin to fdupont

Reviewed commit e5774e21ed68f3ccc0f339affea6487b6cbde47c

Thanks for doing this work. It is nice to see doxygen finally being clean.

That said, I spotted one warning when building docs on OS-X. That is:

Warning: Tag `XML_SCHEMA' at line 1440 of file `-' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
Warning: Tag `XML_DTD' at line 1446 of file `-' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
da/deb/qa:-1: warning: multiple use of section label 'qa', (first occurrence: /Users/marcin/git/kea/doc/devel/mainpage.dox, line 48)

src/lib/dhcpsrv/alloc_engine.h
I suugest that we don't use hyphens when defining anchors. So instead of

/// @anchor findReservation-decl

rather do

/// @anchor findReservationDecl

That will be consistent with the naming of clases and functions.

src/lib/dhcpsrv/alloc_engine_log.cc
The following change:

-/// @file Defines the logger used by the @c isc::dhcp::HostMgr
+/// @brief Defines the logger used by the @c isc::dhcp::HostMgr

doesn't seem to have any effect in the generated documentation. I don't see this note in the documentation, so maybe it will be just ok to remove it?

Also, it should rather be

....  @c isc::dhcp::AllocEngine

src/lib/dhcpsrv/hosts_log.cc
Same comment as for the alloc_engine_log.cc

comment:8 in reply to: ↑ 7 Changed 4 years ago by fdupont

  • Owner changed from fdupont to marcin

Replying to marcin:

Reviewed commit e5774e21ed68f3ccc0f339affea6487b6cbde47c

Thanks for doing this work. It is nice to see doxygen finally being clean.

That said, I spotted one warning when building docs on OS-X. That is:

Warning: Tag `XML_SCHEMA' at line 1440 of file `-' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
Warning: Tag `XML_DTD' at line 1446 of file `-' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
da/deb/qa:-1: warning: multiple use of section label 'qa', (first occurrence: /Users/marcin/git/kea/doc/devel/mainpage.dox, line 48)

=> The doxygen configuration file was written for doxygen 1.8.2, Jenkins VM uses 1.8.6 and OS X has 1.8.10 (latest). I tried to update the config file to make it compatible with 1.8.6 and 1.8.10 (note conflicting variables are set to their default values).

src/lib/dhcpsrv/alloc_engine.h
I suugest that we don't use hyphens when defining anchors. So instead of

/// @anchor findReservation-decl

rather do

/// @anchor findReservationDecl

That will be consistent with the naming of clases and functions.

=> my idea was to make a difference but if you think it was not a good one.

src/lib/dhcpsrv/alloc_engine_log.cc
The following change:

-/// @file Defines the logger used by the @c isc::dhcp::HostMgr
+/// @brief Defines the logger used by the @c isc::dhcp::HostMgr

doesn't seem to have any effect in the generated documentation. I don't see this note in the documentation, so maybe it will be just ok to remove it?

=> the @file was incorrect and this ticket is mainly about fixing warnings.

Also, it should rather be

....  @c isc::dhcp::AllocEngine

=> fixed.

src/lib/dhcpsrv/hosts_log.cc
Same comment as for the alloc_engine_log.cc

=> note there is a warning on OS X (last doxygen) about the section label 'qa'. Is this to be investigated/fixed too?

comment:9 Changed 4 years ago by marcin

  • Owner changed from marcin to fdupont

Reviewed commit 2bee003c2c8fc931ee34c660275f36293bce1f67

I think this needs a ChangeLog entry. Maybe, "Removed warnings emitted during generation of Doxygen documentation".

All ok, please merge.

comment:10 Changed 4 years ago by fdupont

  • Resolution set to fixed
  • Status changed from reviewing to closed

Merged. Closing. Note IMHO we have now to look at the product of doxygen, e.g., I added the stats library in Doxyfile but it is not (yet) in the main page (doc/devel/mainpage.dox).

Note: See TracTickets for help on using tickets.