Re: [Xenomai-help] rt_task_wait_period returns an undocumented value

[Gilles Chanteperdrix <gilles.chanteperdrix@xenomai.org>]

On 10/21/2011 08:08 PM, Fernando Herrero Carrón wrote:
> Alright, excuse me, I missed that explanation.
> 
> Then let me move to the actual figures at hand:
> 
>  $ cat /proc/xenomai/latency
> 3349
> 
> and, as I explained above, all values below 11450 are being rejected in my
> case.

I guess you have to check the code to understand what happens. But
really, running tasks with a 11500 period is already preposterous.

> my point of view. Especially when it refers to documentation, I believe that
> "too much" is never too much.

Conciseness is really important for a documentation, look at an example,
the sentence explaining the -EINVAL return value for
rt_task_make_periodic was a bit long, and you missed the important part,
even though I had told you that it was where was the answer to your
question. So, too much documentation is a problem, because users will
inevitably miss what is important.

Now look at an example outside Xenomai documentation:
http://pubs.opengroup.org/onlinepubs/000095399/functions/pthread_mutex_lock.html

The documentation for EINVAL says:
[EINVAL]
    The value specified by mutex does not refer to an initialized mutex
object.

It does not say, "or an object for which pthread_mutex_init failed", it
is pretty obvious that if pthread_mutex_init failed, the mutex is not
initialized. period.

-- 
                                                                Gilles.