[Ns-developers] [ns3] trace path documentation

[Mathieu Lacage]

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

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

yes, this is true, but, it is much easier to understand
that /ns3::NodeListPriv::NodeList/ identifies attribute NodeList in
class ns3::NodeListPriv than to understand that /NodeList/ does the same
thing or
that /ns3::NodeListPriv::NodeList[*]/ns3::MobilityModelNotifier::CourseChange identifies the CourseChange attribute in class MobilityModelNotifier than to understand that /NodeList/*/$ns3::MobilityModelNotifier/CourseChange does the same thing. i.e., it is really hard to explain why you _absolutely_ need the $TypeId item in one case and not in the other: it is much easier to just say that all items are TypeId::AttributeName.

My concern is not really to explain to a user how to construct a path
but it is to explain to a user how a path is structured and how to
understand what a specific path is doing.

regards,
Mathieu