[Ns-developers] [ns3] trace path documentation

[Mathieu Lacage]

On Sat, 2008-04-12 at 16:11 +0100, Gustavo Carneiro wrote:

>         
>         >   - while working on this code, it occured to me that there
>         are some
>         > ways to somewhat "simplify" the config paths to make them
>         more
>         > consistent. For example, the following would be (I think)
>         much more
>         > consistent:
>         > /NodeList/*/$MobilityModel
>         > to:
>         > /ns3::NodeListPriv::NodeList/*/ns3::MobilityModel
>         >
>         > Basically, we could request the user to specify explicitely
>         each
>         > attribute with a typeid.
> 
> This kind of stuff makes me very uneasy.  Sure it makes NS-3's job
> more easy, but makes the life of NS-3 users much harder.  Who will

The goal is not to make the implementation simpler here (it would not):
it is to make it easier to explain how these paths are constructed. I
have found it _really_ hard to explain the current structure in less
than 2 pages so, while, the proposed structure here is uglier, I believe
that it is easier to explain in a simple way.

>  ever remember a name like "ns3::NodeListPriv::NodeList"?  Or do you

Well, it is really easy: typeid + "::" + attribute name. typeid == c++
classname and users should know the attribute name. So, the above is
long, but it is very descriptive and easy to construct from what users
know, that is, the c++ class name and attribute name.

>  expect that people can only program NS-3 by copy-pasting from
> examples?  That would be a shame...

No, they copy/paste the path strings from the documentation. i.e., if
you look at the generated doxygen for ns-3-doc, you will see that each
type now documents the paths it is accessible from.

> In addition, I thought NS-3 API was supposed to start stabilizing
> already.  Changing an interface that is only matched in run time,
> especially one in which a mis-match is silently ignored, and
> especially making users use names of private classes, is not the way
> to go IMHO.

That is certainly a good point.

Mathieu