Greetings to everyone and a happy new year :)
I was stumbling through the man pages of the proplib functions and I
noticed a few things I would like to discuss with you.
1) For some functions it is not documented what they return if they
fail. Some indicative examples are:
prop_array_create_with_capacity()
prop_array_internalize_from_file()
prop_string_create_cstring()
Most of these return NULL on failure which sounds pretty reasonable
and predictable, but still, shouldn't it be explicitly documented ?
2) prop_xxx_t data types are pointers hidden inside typedef's, e.g
typedef struct _prop_array *prop_array_t;
I understand the purpose of this (data opacity, abstraction, etc), but
wouldn't be nice if this tiny detail was mentioned in proplib(3) man
page?
Knowing that, the following code becomes more intuitive:
prop_array_t pa = prop_array_create_with_capacity(10);
if (pa == NULL) /* How is it possible to check against NULL, if pa
isn't a pointer to sth ? */
...
3) How about some simple code examples in prop_xxx(3) man pages ?
I am willing to provide patches, but first I would like to know what
you think. I might be too pedantic and there is no real need for such
changes.