Opened 7 years ago

Closed 7 years ago

#2982 closed enhancement (complete)

Hooks Framework - Hook Developer Documentation

Reported by: stephen Owned by: stephen
Priority: medium Milestone: Sprint-DHCP-20130731
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 (last modified by stephen)

Produce documentation of the Hooks framework. This comprises two parts:

A description of the framework, together with instructions (and examples) on how to build a user-loadable library. (This does not include a description of the hooks in each server - that is the subject of a separate ticket.)

Subtickets

Change History (7)

comment:1 Changed 7 years ago by stephen

  • Description modified (diff)
  • Summary changed from Hooks Framework - Documentation to Hooks Framework - Hook Developer Documentation

The maintenance documentation was split into a separate ticket, #2999

comment:2 Changed 7 years ago by stephen

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

comment:3 Changed 7 years ago by stephen

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

Now ready for review.

I suggest that reviewers build the developer documentation and review the result, rather than review
the raw Doxygen input.

comment:4 Changed 7 years ago by tmark

  • Owner changed from UnAssigned to stephen

Review comments:

Overall it is well written and easy to follow. Most comments are minor:

Introduction, 3rd paragraph, last sentence says:

"BIND 10 used the modified code in the remainder of its processing."

I think what is meant is:

"BIND 10 uses the modified data in the remainder of its processing."


Introduction, Languages section:

"written into other languages" -> "written in other languages"


Introduction, Terminology section:

"hooks framework for load and unload" -> "hooks framework to load and unload"


Tutorial, Framework Functions, opening sentence:

"Loading an initializing a library" -> "Loading and initializing a library"


Tutorial, Framework Functions, opening sentence:

"although our in out example" -> "although in our example"


Tutorial, The "load and "unload" Functions section:

It mentions "callouts with non-standard names" twice without explaining callout naming first. What is a standard name versus a non-standard name?


Tutorial, Callout Arguments section, under points to be aware of:

"and the underlying object altered" -> "and the underlying object is altered"


Advanced Topics, Context Creation and Destruction

The parenthetical statement:

"(Actually, when the context is destroyed, the destructor associated with any objects stored in it are run. Rather than point to allocated memory with a raw pointer, a better idea would be to point to it with a boost "smart" pointer and store that pointer in the context. When the context is destroyed, the smart pointer's destructor is run, which will automatically delete the pointed-to object.)

is maybe confusing or misleading?

Objects may only be stored in the context using setArugment() method, so if I create an object on the heap as it is based into setArgument(), it would then be destroyed upon context construction:

setArgument("my_object", SomeObject())

or

setArgument("my_object_ptr", SomeObjectPtr(new SomeObject())

right?

It might be good to provide a distinct example or clarify the text.


Advanced Topics, Non-Standard Callout Names:

"we had named out callouts" -> "we had named our callouts"


Advanced Topics, Dynamic Registration and Reregistration of Callouts:

"in that callouts and be registered" -> "in that callouts can be registered"


Advanced Topics, Dynamic Registration and Reregistration of Callouts:

"the callout that wronte the data" -> "the callout that wrote the data"


comment:5 Changed 7 years ago by stephen

  • Owner changed from stephen to tmark

Miscellaneous changes and edits made.

comment:6 Changed 7 years ago by tmark

  • Owner changed from tmark to stephen

One minor correction to make:

Tutorial, Framwork Functions, opening sentence:

"....although our in our example" -> "although in our example"

(Hint, you have an extra "our")

I do not need to see it again.

Are you available for D2 tech documentation? You seem to be pretty good at it ;)

comment:7 Changed 7 years ago by stephen

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

Merged in 26a805c7e49a9ec85ee825f179cda41a2358f4c6

Note: See TracTickets for help on using tickets.