[Ns-developers] [ns3] trace path documentation

[Tom Henderson]

>-----Original Message-----
>From: Tom Henderson [mailto:tomh at tomh.org]
>Sent: Wednesday, April 16, 2008 07:01 AM
>To: 'Mathieu Lacage'
>Cc: 'ns-developers'
>Subject: Re: [Ns-developers] [ns3] trace path documentation
>
>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/.
>

Another question I had was regarding Gustavo's point that we are creating a back-door public interface to non-public objects.
- should it be permissible, or should we hook attributes only to public objects and have the private objects retrieve values from the public objects?
- should retrieving a PointerAttr to a private object be disallowed?  Or is this a non-issue because the class will not be found anyway via the public headers and compilation will fail?

If we stay with the full TypeId for path, should we consider to refactor the node list so that we do not have ns3::NodeListPriv::NodeList but instead ns3::NodeList?

Tom