[getdns-api] API review section 3.1.2 and 3.1.3

[Goyal, Neel]

This is commentary on the latter parts of section 3 in reference to Bob Steagall’s review of the getdns API - http://www.vpnc.org/pipermail/getdns-api/2014-January/000229.html


Section 3.1.2 suggests appending _async to the existing functions where asynchronous behavior is used (I.e. getdns_get_general becomes getdns_get_general_async).  I think this makes sense, given that we have _sync versions of these functions as well.  Since API users are typically used to synch behavior, having the function indicate that it is async may remind them and set expectations.  Essentially, I agree with this proposal.

3.1.3 also makes sense to me - the verb should come first followed by the object beign operated on.  This primarily affects the context methods (i.e. getdns_context_create => getdns_create_context, getdns_context_set_resolution_type => getdns_set_context_resolution_type).  Many code style guidelines follow this idiom.

Thoughts?
“This message (including any attachments) is intended only for the use of the individual or entity to which it is addressed, and may contain information that is non-public, proprietary, privileged, confidential and exempt from disclosure under applicable law or may be constituted as attorney work product. If you are not the intended recipient, you are hereby notified that any use, dissemination, distribution, or copying of this communication is strictly prohibited. If you have received this message in error, notify sender immediately and delete this message immediately.”
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.vpnc.org/pipermail/getdns-api/attachments/20140130/79712216/attachment.html>