Opened 5 years ago

Closed 5 years ago

#3735 closed defect (fixed)

Cleanup the Doxygen errors

Reported by: marcin Owned by: sar
Priority: very low Milestone: Kea0.9.1
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

There is over 100 warnings/errors reported by the Doxygen when performing:

cd doc && make devel

They should be removed.

Subtickets

Change History (7)

comment:1 Changed 5 years ago by hschempf

  • Milestone changed from Kea-proposed to Kea0.9.1
  • Priority changed from low to very low

comment:2 Changed 5 years ago by marcin

There are multiple errors in the Doxygen documentation spotted:

  • libdhcpsrv - AllocEngine? lacks namespace and thus has no link
  • mysql is listed as the only usable backend
  • dhcpDatabaseBackends - no mention of pgsql

comment:3 Changed 5 years ago by sar

  • Owner set to sar
  • Status changed from new to assigned

comment:4 Changed 5 years ago by sar

  • Owner changed from sar to UnAssigned
  • Status changed from assigned to reviewing

I've cleaned up a number of the errors (38 at current count) many of the remainder are in the DNS, ASIO or Bundy code areas.

There are several that aren't in there but they may require changing the source code a bit (vs just comments for all of this patch) and so I'm deferring them.

Ready for review

comment:5 Changed 5 years ago by tmark

  • Owner changed from UnAssigned to tmark

comment:6 Changed 5 years ago by tmark

  • Owner changed from tmark to sar

Rather than using "&lt" and "&gt" for "<" and ">" as you did in the user_chk lib code, it is actually easier and cleaner to bracket sections of text you wish to be treated verbatim with the "code" tag:

@code
/// <id type> text label of the id type: "HW_ADDR" or "DUID"
/// <id str> user's id formatted as either isc::dhcp::Hwaddr.toText() or
@endcode

Please change this. It is much easier to read it inline this way. Applies to src/lib/log/compiler/message.cc also.

Other than that, the changes are fine. Are we creating another ticket for remaining issues?

comment:7 Changed 5 years ago by sar

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

Merged 36338c182bb4b5dda8b2b8b88b7da22952e260b8

The @code construct puts the text into a code block and looks odd for text type items. After a short discussion we decided to leave the text as it is for now and add that cleanup to the new ticket.

Created new ticket 3776 for the remaining warnings and to remove the ugly &lt; and &gt; and replace them with something easier to read in directly.

Note: See TracTickets for help on using tickets.