utils/print-introspected-doxygen.cc
author Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
Mon, 08 Jun 2009 14:14:04 +0200
changeset 4513 544c9d637ff1
parent 4364 579bbfe8bb65
child 4580 8092e3e83487
permissions -rw-r--r--
bug 580: doxygen introspection does not document global values
     1 #include <iostream>
     2 #include "ns3/object.h"
     3 #include "ns3/pointer.h"
     4 #include "ns3/object-vector.h"
     5 #include "ns3/config.h"
     6 #include "ns3/log.h"
     7 #include "ns3/global-value.h"
     8 #include "ns3/string.h"
     9 #include "ns3/helper-module.h"
    10 
    11 using namespace ns3;
    12 
    13 NS_LOG_COMPONENT_DEFINE ("Main");
    14 
    15 void
    16 PrintAttributes (TypeId tid, std::ostream &os)
    17 {
    18   os << "<ul>"<<std::endl;
    19   for (uint32_t j = 0; j < tid.GetAttributeN (); j++)
    20     {
    21       os << "<li><b>" << tid.GetAttributeName (j) << "</b>: "
    22 		<< tid.GetAttributeHelp (j) << std::endl;
    23       Ptr<const AttributeChecker> checker = tid.GetAttributeChecker (j);
    24       os << "  <ul>" << std::endl 
    25 	 << "    <li>Set with class: \\ref " <<  checker->GetValueTypeName () << "</li>" << std::endl;
    26       if (checker->HasUnderlyingTypeInformation ())
    27 	{
    28 	  os << "    <li>Underlying type: \\ref " << checker->GetUnderlyingTypeInformation () << "</li>" << std::endl;
    29 	}
    30       uint32_t flags = tid.GetAttributeFlags (j);
    31       Ptr<const AttributeAccessor> accessor = tid.GetAttributeAccessor (j);
    32       if (flags & TypeId::ATTR_CONSTRUCT && accessor->HasSetter ())
    33 	{
    34 	  Ptr<const AttributeValue> initial = tid.GetAttributeInitialValue (j);
    35 	  os << "    <li>Initial value: " << initial->SerializeToString (checker) << "</li>" << std::endl;
    36 	}
    37       os << "    <li>Flags: ";
    38       if (flags & TypeId::ATTR_CONSTRUCT && accessor->HasSetter ())
    39 	{
    40 	  os << "construct ";
    41 	}
    42       if (flags & TypeId::ATTR_SET && accessor->HasSetter ())
    43 	{
    44 	  os << "write ";
    45 	}
    46       if (flags & TypeId::ATTR_GET && accessor->HasGetter ())
    47 	{
    48 	  os << "read ";
    49 	}
    50       os << "</li>" << std::endl;
    51       os << "  </ul> " << std::endl;
    52       
    53     }
    54   os << "</ul>" << std::endl;
    55 }
    56 
    57 void
    58 PrintTraceSources (TypeId tid, std::ostream &os)
    59 {
    60   os << "<ul>"<<std::endl;
    61   for (uint32_t i = 0; i < tid.GetTraceSourceN (); ++i)
    62     {
    63       os << "<li><b>" << tid.GetTraceSourceName (i) << "</b>: "
    64 	 << tid.GetTraceSourceHelp (i)
    65 	 << std::endl;
    66       os << "</li>" << std::endl;
    67     }
    68   os << "</ul>"<<std::endl;
    69 }
    70 
    71 
    72 class StaticInformation
    73 {
    74 public:
    75   void RecordAggregationInfo (std::string a, std::string b);
    76   void Gather (TypeId tid);
    77   void Print (void) const;
    78 
    79   std::vector<std::string> Get (TypeId tid);
    80 
    81 private:
    82   std::string GetCurrentPath (void) const;
    83   void DoGather (TypeId tid);
    84   void RecordOutput (TypeId tid);
    85   bool HasAlreadyBeenProcessed (TypeId tid) const;
    86   std::vector<std::pair<TypeId,std::string> > m_output;
    87   std::vector<std::string> m_currentPath;
    88   std::vector<TypeId> m_alreadyProcessed;
    89   std::vector<std::pair<TypeId,TypeId> > m_aggregates;
    90 };
    91 
    92 void 
    93 StaticInformation::RecordAggregationInfo (std::string a, std::string b)
    94 {
    95   m_aggregates.push_back (std::make_pair (TypeId::LookupByName (a), TypeId::LookupByName (b)));
    96 }
    97 
    98 void 
    99 StaticInformation::Print (void) const
   100 {
   101   for (std::vector<std::pair<TypeId,std::string> >::const_iterator i = m_output.begin (); i != m_output.end (); ++i)
   102     {
   103       std::pair<TypeId,std::string> item = *i;
   104       std::cout << item.first.GetName () << " -> " << item.second << std::endl;
   105     }
   106 }
   107 
   108 std::string
   109 StaticInformation::GetCurrentPath (void) const
   110 {
   111   std::ostringstream oss;
   112   for (std::vector<std::string>::const_iterator i = m_currentPath.begin (); i != m_currentPath.end (); ++i)
   113     {
   114       std::string item = *i;
   115       oss << "/" << item;
   116     }
   117   return oss.str ();
   118 }
   119 
   120 void
   121 StaticInformation::RecordOutput (TypeId tid)
   122 {
   123   m_output.push_back (std::make_pair (tid, GetCurrentPath ()));
   124 }
   125 
   126 bool
   127 StaticInformation::HasAlreadyBeenProcessed (TypeId tid) const
   128 {
   129   for (uint32_t i = 0; i < m_alreadyProcessed.size (); ++i)
   130     {
   131       if (m_alreadyProcessed[i] == tid)
   132 	{
   133 	  return true;
   134 	}
   135     }
   136   return false;
   137 }
   138 
   139 std::vector<std::string> 
   140 StaticInformation::Get (TypeId tid)
   141 {
   142   std::vector<std::string> paths;
   143   for (uint32_t i = 0; i < m_output.size (); ++i)
   144     {
   145       std::pair<TypeId,std::string> tmp = m_output[i];
   146       if (tmp.first == tid)
   147 	{
   148 	  paths.push_back (tmp.second);
   149 	}
   150     }
   151   return paths;
   152 }
   153 
   154 void
   155 StaticInformation::Gather (TypeId tid)
   156 {
   157   DoGather (tid);
   158 
   159   std::sort (m_output.begin (), m_output.end ());
   160   m_output.erase (std::unique (m_output.begin (), m_output.end ()), m_output.end ());
   161 }
   162 
   163 void 
   164 StaticInformation::DoGather (TypeId tid)
   165 {
   166   NS_LOG_FUNCTION (this);
   167   if (HasAlreadyBeenProcessed (tid))
   168     {
   169       return;
   170     }
   171   RecordOutput (tid);
   172   for (uint32_t i = 0; i < tid.GetAttributeN (); ++i)
   173     {
   174       Ptr<const AttributeChecker> checker = tid.GetAttributeChecker (i);
   175       const PointerChecker *ptrChecker = dynamic_cast<const PointerChecker *> (PeekPointer (checker));
   176       if (ptrChecker != 0)
   177 	{
   178 	  TypeId pointee = ptrChecker->GetPointeeTypeId ();
   179 	  m_currentPath.push_back (tid.GetAttributeName (i));
   180 	  m_alreadyProcessed.push_back (tid);
   181 	  DoGather (pointee);
   182 	  m_alreadyProcessed.pop_back ();
   183 	  m_currentPath.pop_back ();
   184 	  continue;
   185 	}
   186       // attempt to cast to an object vector.
   187       const ObjectVectorChecker *vectorChecker = dynamic_cast<const ObjectVectorChecker *> (PeekPointer (checker));
   188       if (vectorChecker != 0)
   189 	{
   190 	  TypeId item = vectorChecker->GetItemTypeId ();
   191 	  m_currentPath.push_back (tid.GetAttributeName (i) + "/[i]");
   192 	  m_alreadyProcessed.push_back (tid);
   193 	  DoGather (item);
   194 	  m_alreadyProcessed.pop_back ();
   195 	  m_currentPath.pop_back ();
   196 	  continue;
   197 	}
   198     }
   199   for (uint32_t j = 0; j < TypeId::GetRegisteredN (); j++)
   200     {
   201       TypeId child = TypeId::GetRegistered (j);
   202       if (child.IsChildOf (tid))
   203 	{
   204 	  m_currentPath.push_back ("$%" + child.GetName ());
   205 	  m_alreadyProcessed.push_back (tid);
   206 	  DoGather (child);
   207 	  m_alreadyProcessed.pop_back ();
   208 	  m_currentPath.pop_back ();
   209 	}
   210     }
   211   for (uint32_t k = 0; k < m_aggregates.size (); ++k)
   212     {
   213       std::pair<TypeId,TypeId> tmp = m_aggregates[k];
   214       if (tmp.first == tid || tmp.second == tid)
   215 	{
   216 	  TypeId other;
   217 	  if (tmp.first == tid)
   218 	    {
   219 	      other = tmp.second;
   220 	    }
   221 	  if (tmp.second == tid)
   222 	    {
   223 	      other = tmp.first;
   224 	    }
   225 	  // Note: we insert a % in the path below to ensure that doxygen does not
   226 	  // attempt to resolve the typeid names included in the string.
   227 	  m_currentPath.push_back ("$%" + other.GetName ());
   228 	  m_alreadyProcessed.push_back (tid);
   229 	  DoGather (other);
   230 	  m_alreadyProcessed.pop_back ();
   231 	  m_currentPath.pop_back ();	  
   232 	}
   233     }
   234 }
   235 
   236 int main (int argc, char *argv[])
   237 {
   238   NodeContainer c; c.Create (1);
   239 
   240   StaticInformation info;
   241   info.RecordAggregationInfo ("ns3::Node", "ns3::TcpSocketFactory");
   242   info.RecordAggregationInfo ("ns3::Node", "ns3::UdpSocketFactory");
   243   info.RecordAggregationInfo ("ns3::Node", "ns3::PacketSocketFactory");
   244   info.RecordAggregationInfo ("ns3::Node", "ns3::olsr::RoutingProtocol");
   245   info.RecordAggregationInfo ("ns3::Node", "ns3::MobilityModel");
   246   info.RecordAggregationInfo ("ns3::Node", "ns3::Ipv4L3Protocol");
   247   info.RecordAggregationInfo ("ns3::Node", "ns3::ArpL3Protocol");
   248 
   249   for (uint32_t i = 0; i < Config::GetRootNamespaceObjectN (); ++i)
   250     {
   251       Ptr<Object> object = Config::GetRootNamespaceObject (i);
   252       info.Gather (object->GetInstanceTypeId ());
   253     }
   254 
   255   for (uint32_t i = 0; i < TypeId::GetRegisteredN (); i++)
   256     {
   257       std::cout << "/*!" << std::endl;
   258       TypeId tid = TypeId::GetRegistered (i);
   259       if (tid.MustHideFromDocumentation ())
   260 	{
   261 	  continue;
   262 	}
   263       std::cout << "\\fn static TypeId " << tid.GetName () << "::GetTypeId (void)" << std::endl;
   264       std::cout << "\\brief This method returns the TypeId associated to \\ref " << tid.GetName () 
   265 		<< std::endl << std::endl;
   266       std::vector<std::string> paths = info.Get (tid);
   267       if (!paths.empty ())
   268 	{
   269 	  std::cout << "This object is accessible through the following paths with Config::Set and Config::Connect:" 
   270 		    << std::endl;
   271 	  std::cout << "<ul>" << std::endl;
   272 	  for (uint32_t k = 0; k < paths.size (); ++k)
   273 	    {
   274 	      std::string path = paths[k];
   275 	      std::cout << "<li>" << path << "</li>" << std::endl;
   276 	    }
   277 	  std::cout << "</ul>" << std::endl;
   278 	}
   279       if (tid.GetAttributeN () == 0)
   280 	{
   281 	  std::cout << "No Attributes defined for this type.<br>" << std::endl;
   282 	}
   283       else
   284 	{
   285 	  std::cout << "Attributes defined for this type:<br>" << std::endl;
   286 	  PrintAttributes (tid, std::cout);
   287 	}
   288       {
   289 	TypeId tmp = tid.GetParent ();
   290 	while (tmp.GetParent () != tmp)
   291 	  {
   292 	    if (tmp.GetAttributeN () != 0)
   293 	      {
   294 		std::cout << "Attributes defined in parent class " << tmp.GetName () << ":<br>" << std::endl;
   295 		PrintAttributes (tmp, std::cout);
   296 	      }
   297 	    tmp = tmp.GetParent ();
   298 	  }
   299       }
   300       if (tid.GetTraceSourceN () == 0)
   301 	{
   302 	  std::cout << "No TraceSources defined for this type.<br>" << std::endl;
   303 	}
   304       else
   305 	{
   306 	  std::cout << "TraceSources defined for this type:<br>" << std::endl;
   307 	  PrintTraceSources (tid, std::cout);
   308 	}
   309       {
   310 	TypeId tmp = tid.GetParent ();
   311 	while (tmp.GetParent () != tmp)
   312 	  {
   313 	    if (tmp.GetTraceSourceN () != 0)
   314 	      {
   315 		std::cout << "TraceSources defined in parent class " << tmp.GetName () << ":<br>" << std::endl;
   316 		PrintTraceSources (tmp, std::cout);
   317 	      }
   318 	    tmp = tmp.GetParent ();
   319 	  }
   320       }
   321       std::cout << "*/" << std::endl;
   322     }
   323 
   324 
   325   std::cout << "/*!" << std::endl
   326 	    << "\\ingroup core" << std::endl
   327 	    << "\\defgroup TraceSourceList The list of all trace sources." << std::endl;
   328   for (uint32_t i = 0; i < TypeId::GetRegisteredN (); ++i)
   329     {
   330       TypeId tid = TypeId::GetRegistered (i);
   331       if (tid.GetTraceSourceN () == 0 ||
   332 	  tid.MustHideFromDocumentation ())
   333 	{
   334 	  continue;
   335 	}
   336       std::cout << "<b>" << tid.GetName () << "</b><br>" << std::endl
   337 		<< "<ul>" << std::endl;
   338       for (uint32_t j = 0; j < tid.GetTraceSourceN (); ++j)
   339 	{
   340 	  std::cout << "<li>" << tid.GetTraceSourceName (j) << ": " << tid.GetTraceSourceHelp (j) << "</li>" << std::endl;
   341 	}
   342       std::cout << "</ul>" << std::endl;
   343     }
   344   std::cout << "*/" << std::endl;
   345 
   346 
   347   std::cout << "/*!" << std::endl
   348 	    << "\\ingroup core" << std::endl
   349 	    << "\\defgroup AttributeList The list of all attributes." << std::endl;
   350   for (uint32_t i = 0; i < TypeId::GetRegisteredN (); ++i)
   351     {
   352       TypeId tid = TypeId::GetRegistered (i);
   353       if (tid.GetAttributeN () == 0 ||
   354 	  tid.MustHideFromDocumentation ())
   355 	{
   356 	  continue;
   357 	}
   358       std::cout << "<b>" << tid.GetName () << "</b><br>" << std::endl
   359 		<< "<ul>" << std::endl;
   360       for (uint32_t j = 0; j < tid.GetAttributeN (); ++j)
   361 	{
   362 	  std::cout << "<li>" << tid.GetAttributeName (j) << ": " << tid.GetAttributeHelp (j) << "</li>" << std::endl;
   363 	}
   364       std::cout << "</ul>" << std::endl;
   365     }
   366   std::cout << "*/" << std::endl;
   367 
   368 
   369 
   370   std::cout << "/*!" << std::endl
   371 	    << "\\ingroup core" << std::endl
   372 	    << "\\defgroup GlobalValueList The list of all global values." << std::endl
   373 	    << "<ul>" << std::endl;
   374   for (GlobalValue::Iterator i = GlobalValue::Begin (); i != GlobalValue::End (); ++i)
   375     {
   376       StringValue val;
   377       (*i)->GetValue (val);
   378       std::cout << "  <li><b>" << (*i)->GetName () << "</b>: " << (*i)->GetHelp () << "(" << val.Get () << ")</li>" << std::endl;
   379     }
   380   std::cout << "</ul>" << std::endl
   381 	    << "*/" << std::endl;
   382 
   383 
   384   return 0;
   385 }