[Ns-developers] [ns3] trace path documentation

[Gustavo Carneiro]

On 12/04/2008, Mathieu Lacage <mathieu.lacage at sophia.inria.fr> wrote:
>
>
> 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.


But the users do not know the class name.  NodeListPriv is a hidden class;
does not even appear in any header file.

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


-- 
Gustavo J. A. M. Carneiro
INESC Porto, Telecommunications and Multimedia Unit
"The universe is always one step beyond logic." -- Frank Herbert