Bug 442

(In reply to comment #0)
> We have lots of trace sources in the various net devices in the system, but
> exactly what they do is not clear without reading and understanding a
> significant amount of code.  We should have some form of higher level
> documentation that is easy to find and understand.  For net devices, each
> should have a model description and part of that description should be what the
> trace sources are tracing.
> 

We do have this documentation:
http://www.nsnam.org/doxygen/group___trace_source_list.html

What is not clear from the above is:
- that one can hook ns3::Queue traces in these devices
- what the helper API does for each device

So I agree that there should be a section of documentation for each device that provides an overview of all possible trace sources for the device, and then there should be somewhere some description of what steps are done to try to ensure some consistency in the standard (ASCII and PCAP) trace output at the helper API-- how it relates to libpcap trace points, for instance.  I think the manual is appropriate for this stuff.

Yes, we have a list of all trace sources.  It is incomplete, and the "documentation" of each trace source is the help string of the corresponding attribute.  IMO This is woefully inadequate and a completely inappropriate place to stash primary documentation.

I think there needs to be a well-known place a user can go in our doxygen to find out what exactly is being done.  Three levels of documentation make sense:  1) the help string; 2) an easily found doxygen comment describing what the trace hook actually does; 3) a manual entry covering all bases.  People would probably be exposed to the documentation in that order.

IMO as it exists, the list of all trace sources is just a convenient partial list -- not "real" documentation.

We have agreed on a three-level solution to this bug

Level 1) Help strings are to be made more descriptive so they make sense in the list of all trace sources.

Level 2) In the model descriptions, we need to address HASA trace source relationships and describe when trace hooks are hit.

Level 3) In the manual, there will be new sections added for the devices that will allow very detailed explanations.

Made help strings on device trace sources more descriptive.
Added trace info to model descriptions in doxygen.
Added manual sections for devices (wifi done separately).