[Ns-developers] Proposed Simulator Changes

[Tom Henderson]

>>>> 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.

Tom