[getdns-api] API review section 3.1.2 and 3.1.3

[Wiley, Glen]

I agree that this will reduce the effort required for new/infrequent users of the API – I recommend the change.
--
Glen Wiley
KK4SFV
Sr. Engineer
The Hive, Verisign, Inc.

From: <Goyal>, Neel <ngoyal at verisign.com<mailto:ngoyal at verisign.com>>
Date: Thursday, January 30, 2014 11:12 AM
To: "getdns-api at vpnc.org<mailto:getdns-api at vpnc.org>" <getdns-api at vpnc.org<mailto:getdns-api at vpnc.org>>
Subject: [getdns-api] API review section 3.1.2 and 3.1.3


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/c07fe68a/attachment-0001.html>