[Ns-developers] Proposed Simulator Changes
gjcarneiro at gmail.com
Tue Oct 14 08:31:22 PDT 2008
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
>>>> 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
>>> have unilaterally decided on? I always thought that documentation should
>>> 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.
Gustavo J. A. M. Carneiro
INESC Porto, Telecommunications and Multimedia Unit
"The universe is always one step beyond logic." -- Frank Herbert
More information about the Ns-developers