tech-kern archive

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]

Re: proplib documentantion enhancements

On Jan,Friday 4 2008, at 2:04 PM, S K wrote:

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:


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

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

Go for it. All patches are welcome!



Home | Main Index | Thread Index | Old Index