[Ns-developers] Proposed Simulator Changes

[Gustavo Carneiro]

2008/10/14 Tom Henderson <tomh at tomh.org>

>
>
>  I could be convinced that moving these methods back into Simulator
>>>>> would be
>>>>> okay if we plastered enough warning signs all over them.  If you
>>>>> actually
>>>>>
>>>> Feel free to do so, ?but, please, make sure that no method documentation
>>>> is longer than 3 paragraphs.
>>>>
>>> Is this some kind of new and undiscussed documentation requirement that
>>> you
>>> have unilaterally decided on?  I always thought that documentation should
>>> be
>>> sufficient to document the behavior of the function.
>>>
>>
>> This kind of irony is not very productive: you know very well that I
>> don't want insufficient documentation and I am fairly certain that you
>> know why I added that comment because I already mentioned the below to
>> you while casually chatting. When I read, 'plastering enough warning
>> signs' from craig, I know that it means 2-page comments inserted in the
>> documentation and I believe that this makes the documentation useless:
>> no one reads a 2-page documentation for a function.
>> So, I am not asking you to make the documentation be insufficient: I am
>> asking you to make your sufficient documentation fit a 3-paragraph limit
>> and I would like to add another constraint: no paragraph should be
>> longer than 5 lines. I think that it will improve the usefulness of the
>> resulting documentation and I specifically added this comment for you
>> because you are the only person to generate such prolific documentation.
>>
>> If you consider this to be an unfair unilateral decision, I would be
>> happy to submit that specific request for larger discussion among ns3
>> maintainers and defer the decision to a consensus but I believe that the
>> above request is pretty reasonable for the code I maintain and falls
>> within the bounds of maintainer authority.
>>
>>
> Although I don't think this issue exists with the rts code right now, I
> think it is reasonable to allow a maintainer to ask contributors that
> lengthy Doxygen documentation be either shortened or moved into the ns-3
> manual, without setting a strict limit.


IMHO, when extensive documentation exists it should have two levels of
detail.  A first level should be concise and clear, and include a link for a
section (or another document) with more extensive information.  This should
make everybody happy, I think.

Regards.

-- 
Gustavo J. A. M. Carneiro
INESC Porto, Telecommunications and Multimedia Unit
"The universe is always one step beyond logic." -- Frank Herbert