[getdns-api] Memory part 2 - get and set

[Willem Toorop]

The specification doesn't say anything about memory ownership with the
getdns_(dict|list)_(get|set)_ functions.

To reduce the amount of memory-copies, optimize performance and to
provide the most intuitive interface, in our implementation we have
chosen to let the getters return references to values (except for ints)
and let the setters copy the given value.

It would be wise to document this behaviour in the specification.

I propose to insert to following text before the last paragraph in
section 2:

	The helper getter functions return references to getdns_dict,
	getdns_list and getdns_bindata data structures.  It is
	important that the user does not destroy these retrieved
	"child" data structures themselves.  They will automatically be
	destroyed when the containing "parent" data structure is
	destroyed.  Also, retrieved "child" data structures can not be
	used any more after the containing "parent" data structure has
	been destroyed.

Should we also mention that a "child" data structure must be destroyed
by the user when it is replaced with a different value in the "parent"
data structure?


For the setters I propose this text to be the last paragraph of section 2.1:

	The helper setter functions store copies of the given "child"
	values.  It is the responsibility of the call to dispose of the
	original values.


What do you think?