[Ns-developers] [ns3] trace path documentation

[Tom Henderson]

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

Mathieu,

Thanks for doing all of this documentation work; I think it will be very 
helpful and it starts to show the benefits of our move to attributes.

I built your ns-3-doc doxygen today and found this sample path:

"This object is accessible through the following paths with Config::Set 
and Config::Connect:
     /NodeList/[i]/DeviceList/[i]/$ns3PointToPointNetDevice"

Are you considering now to move away from full TypeId to the above 
(based on Gustavo's posts earlier this week), or is your documentation 
not fully functional?

I suspect it is the latter, but as you know, it would still make me 
happier to support paths like the above instead of e.g. 
/ns3::NodeListPriv::NodeList/.

- Tom