[getdns-api] API review section 3.1.2 and 3.1.3

[Paul Hoffman]

On Jan 30, 2014, at 8:12 AM, Goyal, Neel <ngoyal at verisign.com> wrote:

> 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.

One of the main features of the library that hasn't existed in earlier libraries is that it is async. The "_sync" versions were thrown in at the end of the process because some developers wanted that, but by and large the library lives and breathes on async usage.

Another way to look at this is that if you're looking at the arguments of a function call and you can't tell that it is async, you're in way over your head.

So, please: let's not make the call names longer than needed.

> 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.

Sure, whatever. This helps literally no one after the first few minutes of them learning the API, but it seems like a harmless change.

--Paul Hoffman