[Ns-developers] wifi-adhoc.cc

[craigdo@ee.washington.edu]

> >> What is the wifi-ad-hoc experiment stuff?
> > 
> > examples/wifi-adhoc.cc
> > 
> > Questions about why it takes so long to run, or whether it 
> is broken or not
> > pop up on the list every once in a while.
> 
> So, is there anything that could/should be done about it: 
> documentation?
> more explicit logging? a test to check it is not broken? a 
> rewrite? Any
> other suggestion?

There are a few issues here that I think run much deeper than adding a few
lines of code, or even writing some words.

- We are using most of the example programs to do double-duty as regression
tests.  This is not a good long-term solution for testing.  We need a "real"
test strategy, test harness and test programs to fully exercise our system.
The examples should be treated as examples.

- There really isn't any strategy for what kind of examples should be
present to lead users through the system.  IMO, ideally, the example
programs should be tied to a tutorial and documentation system; and what the
examples do and how they behave should be very thoroughly explained.

- If I remember correctly, only three of those example programs have any
kind of documentation associated with them and this is all in the single
tutorial.  Many of the examples are really mostly smoke-test programs that
show a little about how to use a facility.

- There should be some kind of "directory" documentation pointing to
examples indexed by common tasks.  For example, if someone wants to learn
how to do real experiments on a wifi network, they should be able to go to
our documentation and look up wifi.  There, they should find tutorials on
how to understand some simple examples, and find a path that progresses them
to eventually  work with something like wifi-adhoc and explain what it does,
why it may take a long time to run, and how they can make a few simple
changes.

So, in order to sort this out I think we need to work on defining a test
strategy and stop using examples as test programs.  Then I think this
becomes primarily a documentation issue.  We need some consistent kind of
documentation structure in which to document and "tutorialize" the resulting
examples, with some real strategy on what kind of examples we need and how
they tie into a larger picture.

The problem, of course, is that I just described dedicated an ns-3 world
with test and documentation organizations filled with test engineers and
writers.  We don't have these people.  Perhaps the best thing to do is to
find fairly dedicated maintainers for a test system and documentation.  A
couple of us have been trying to keep some level of dox and tests in place,
but we are very wanting in those departments.

Regards,

-- Craig