[Ns-developers] Proposed Simulator Changes

[craigdo@ee.washington.edu]

[ ... ]

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

It wasn't intended to be ironic or sarcastic.

You don't *know* that "plastering warning signs" means 2-page comments
inserted in the documentation.  You seem to have *imagined* it would be
2-page comments with absolutely no supporting evidence.  What I meant was an
@warning on the methods:

 * @warning This method is not multithread safe.  Do not call outside
 * the context of a scheduled simulator event.

Hardly two pages of documentation.  You can't be thinking about other
existing doxygen either, based on what I've added.  Here's what I wrote for
the new simulator class:

/**
 * \ingroup simulator
 *
 * \brief Extension class to control the scheduling of real-time simulation
 * events.  Intended to be used by threads driven by "external" system
 * events and will schedule events using the current real-time instead of
 * the current simulation time.
 */

Hardly two pages of needlessly wordy comments.

I do have a cumulative couple of pages of comments in ProcessOneEvent, which
describes how the real-time synchronization process works, but I don't think
they are excessive.  They describe situations which I don't think are at all
obvious and may even look like bugs at first glance.  If you think it's
intuitively obvious what is happening, well, good for you.  I think these
comments are valuable for the rest of us.

I'm not objecting to the idea that documentation should be concise, what I'm
really annoyed at is the last-minute changes in acceptance criteria, and
especially these apparently arbitrary restrictions and edicts that have
popped up for every submission and design review I can recall in this
project.

> no one reads a 2-page documentation for a function.

In my experience nobody ever reads documentation, period.  That is, nobody
reads documentation unless they have a reason to.  In my experience nobody
ever reads long documentation.  That is, they don't read it unless they have
a reason to.

Sometimes two-page method documentation really does need to be there.
Sometimes it should be short, sometimes it should be long.  Sometimes even
longer than two pages.  Look at the documentation for memset().  It's just a
few words.  Look at the documentaioon for socket().  It's something like
seven pages.  I think this reflects reality.  You write enough to document
the method, you don't arbitrarily demand that no documentation can be longer
than some random paragraph or sentence limit because you imagine someone may
write something that you think is too wordy.

You also said that saying this was not productive.  I think that saying it
reflected obvious reality.

Regarding productivity, instead of just dictating arbitrary new rules, you
might have looked at my documentation and pointed out what you thought was
excessively wordy and asked me about it.  Then, we wouldn't be having this
conversation and I wouldn't be ticked-off.

In any case, there simply are no 2-page method documentation comments in the
code.
 
> 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.

Where is this a problem for crying out loud?  Where are all of these giant
two-page doxygen entries that nobody is going to read?  I can think of only
one place I have ever written a very long doxygen (in an entirely different
module); but I think a long explanation is justified, just like I think the
Unix socket() documentation is justified.

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

I consider this an unfair unilateral decision.  I found it overly officious
and lacking any basis.

That said, you are the maintainer of src/simulator, so you can demand that I
strip all of the comments out of the code and document the methods in
caveman grunts if you want.  This doesn't sound like a very open and
collaborative environment, though.  

My bottom line is that I would really appreciate it if you could limit
yourself to addressing real existing situations instead of making
pseudorandom edicts or sweeping editorial comments.

Do you actually have an issue with the doxygen in the simulator files I've
added?