Opened 8 years ago

Closed 8 years ago

#1531 closed enhancement (fixed)

Write documentation for libdhcp++

Reported by: tomek Owned by: tomek
Priority: medium Milestone: Sprint-DHCP-20120514
Component: documentation Version:
Keywords: Cc:
CVSS Scoring: Parent Tickets:
Sensitive: no Defect Severity: N/A
Sub-Project: DHCP Feature Depending on Ticket:
Estimated Difficulty: 0 Add Hours to Ticket: 0
Total Hours: 0 Internal?: no

Description

This is a follow up to #1367 that turned out to become "write BIND10 Guide for DHCP components".

Every method and class variable is documented in libdhcp. What is missing is "the big picture". How to use it, what it is for, how to do certain tasks. etc.

Doxygen page should be extended.

I propose to do something similar, as was done in Dibbler. See Section 5 here for extensive example: http://klub.com.pl/dhcpv6/doxygen/.

Subtickets

Change History (11)

comment:1 Changed 8 years ago by tomek

The intended readers of this documentation are developers. Documentation for users is BIND10 Guide, see ticket #1367.

Last edited 8 years ago by tomek (previous) (diff)

comment:2 Changed 8 years ago by tomek

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

comment:3 Changed 8 years ago by stephen

  • Milestone changed from DHCP 2012 to Sprint-DHCP-20120305

comment:4 Changed 8 years ago by tomek

  • Owner changed from tomek to UnAssigned
  • Status changed from accepted to reviewing

Documentation updated. This ticket should be named "generic developer's guide update" rather than "libdhcp++ documentation", but libdhcp++ is still major part of the work.

Please review.

comment:5 Changed 8 years ago by stephen

  • Owner changed from UnAssigned to stephen

comment:6 Changed 8 years ago by stephen

  • Owner changed from stephen to tomek

Checked it and all seems OK. Good idea to have a formal programming guide.

I have some nits issues concerning syntax and grammar, but I think these are best tackled in another ticket that does an editorial review of the programmers' guide as a whole.

I suggest running it past the rest of the team (at the DHCP/DNS day at the F2F) before committing it. We need to get their buy-in to expand the documentation.

comment:7 Changed 8 years ago by tomek

  • Owner changed from tomek to jreed

comment:8 follow-up: Changed 8 years ago by jreed

Here are my comments:

  1. The make devel output of wc -l is wrong. As multiple lines counted for single warning.

Maybe use:

        echo `grep -i ": warning:" html/doxygen-error.log | wc -l` warnings detected.
  1. no corresponding clean target
  1. Maybe link on left list to BIND10 Developer's Guide should say Index or front page.
  1. I am not sure what "Related Pages" is for.
  1. The PROJECT_NAME should be BIND10. The PROJECT_NUMBER could be set to the PACKAGE_VERSION (in Makefile).
  1. Add link to the operators guide.

These are just minor. So please just merge this in now. Thank you for your work on this. (I may make some the minor adjustments later.)

comment:9 Changed 8 years ago by jreed

  • Owner changed from jreed to tomek

comment:10 in reply to: ↑ 8 Changed 8 years ago by tomek

Replying to jreed:

Here are my comments:

  1. The make devel output of wc -l is wrong. As multiple lines counted for single warning.

Maybe use:

        echo `grep -i ": warning:" html/doxygen-error.log | wc -l` warnings detected.

Done.

  1. no corresponding clean target

Added.

  1. Maybe link on left list to BIND10 Developer's Guide should say Index or front page.

I don't know how to make the page title and link to it different on the left list.

  1. I am not sure what "Related Pages" is for.

It is being generated automatically. I failed to find out any obvious way to disable its generation.

  1. The PROJECT_NAME should be BIND10. The PROJECT_NUMBER could be set to the PACKAGE_VERSION (in Makefile).

Done. There's a slightly tricky way of passing variable to doxygen (using pipe, as recommended on doxygen faq page). It works ok for one variable, but will look very ugly if there are more parameters to pass. If that will be the case, we should consider migrating to Doxyfile.in and generating it during configure phase.

  1. Add link to the operators guide.

Done.

These are just minor. So please just merge this in now. Thank you for your work on this. (I may make some the minor adjustments later.)

I will create a separate ticket for all outstanding comments you made here and over mail (adding python modules to documentation).

Thanks for the review.

Tomek

comment:11 Changed 8 years ago by tomek

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

Code pushed to master.

See #1961 for outstanding things to do.

Closing ticket.

Note: See TracTickets for help on using tickets.