BIND 10 #2982: Hooks Framework - Hook Developer Documentation

[BIND 10 Development]

#2982: Hooks Framework - Hook Developer Documentation
-------------------------------------+-------------------------------------
            Reporter:  stephen       |                        Owner:
                Type:  enhancement   |  stephen
            Priority:  medium        |                       Status:
           Component:                |  reviewing
  documentation                      |                    Milestone:
            Keywords:                |  Sprint-DHCP-20130717
           Sensitive:  0             |                   Resolution:
         Sub-Project:  DHCP          |                 CVSS Scoring:
Estimated Difficulty:  0             |              Defect Severity:  N/A
         Total Hours:  0             |  Feature Depending on Ticket:
                                     |          Add Hours to Ticket:  0
                                     |                    Internal?:  0
-------------------------------------+-------------------------------------
Changes (by tmark):

 * owner:  UnAssigned => stephen


Comment:

 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"

 ----------------------------------

-- 
Ticket URL: <http://bind10.isc.org/ticket/2982#comment:4>
BIND 10 Development <http://bind10.isc.org>
BIND 10 Development