diff --git a/doc/doxygen.conf b/doc/doxygen.conf index 5a2af5311..668712036 100644 --- a/doc/doxygen.conf +++ b/doc/doxygen.conf @@ -245,6 +245,16 @@ ALIASES += pname{1}="RFC \1" +## Highlight template parameter induction +## Inferred template parameters are clear from the context: +## template void Func (T x); +## Explicit template parameters must be given at the call site: +## template void Func (void); +## which is called as +## Func (); +ALIASES += deduced="[deduced] " +ALIASES += explicit="[explicit]" + # This tag can be used to specify a number of word-keyword mappings (TCL only). # A mapping has the form "name=value". For example adding "class=itcl::class" # will allow you to use the command class in the itcl::class meaning. @@ -546,7 +556,7 @@ SHOW_GROUPED_MEMB_INC = NO # files with double quotes in the documentation rather than with sharp brackets. # The default value is: NO. -FORCE_LOCAL_INCLUDES = NO +FORCE_LOCAL_INCLUDES = YES # If the INLINE_INFO tag is set to YES then a tag [inline] is inserted in the # documentation for inline members. diff --git a/doc/manual/source/documentation.rst b/doc/manual/source/documentation.rst index d608deeba..072e0802c 100644 --- a/doc/manual/source/documentation.rst +++ b/doc/manual/source/documentation.rst @@ -38,7 +38,8 @@ Documenting with Sphinx We use Sphinx_ to generate expository chapters describing the design and usage of each module. Right now you are reading the :doc:`Documentation ` Chapter. -The `Show Source <_sources/documentation.txt>`_ link in the sidebar +If you are reading the html version, the +`Show Source <_sources/documentation.txt>`_ link in the sidebar will show you the reStructuredText source for this chapter. Adding New Chapters @@ -59,7 +60,7 @@ top-level document for the module. The ``src/create-module.py`` script will create this file for you. Some models require several ``.rst`` files, and figures; these should -all go in the ``src/foo/doc/`` directory. The docs are actually build +all go in the ``src/foo/doc/`` directory. The docs are actually built by a Sphinx Makefile. For especially involved documentation, it may be helpful to have a local ``Makefile`` in the ``src/foo/doc/`` directory to @@ -137,7 +138,7 @@ To build just the Models documentation: .. sourcecode:: bash - $ make -C doc/models + $ make -C doc/models html To see the generated documentation point your browser at ``doc/models/build/html``. @@ -260,7 +261,7 @@ provides a number of useful features: * Summary table of all class members. * Graphs of inheritance and collaboration for all classes. - * Links to the source code imlementing each function. + * Links to the source code implementing each function. * Links to every place a member is used. * Links to every object used in implementing a function. * Grouping of related classes, such as all the classes related to @@ -273,6 +274,7 @@ for every class * Documentation for any ``Attributes``, including ``Attributes`` defined in parent classes. * Documentation for any ``Trace`` sources defined by the class. + * The memory footprint for each class. Doxygen operates by scaning the source code, looking for specially marked comments. It also creates a cross reference, @@ -368,91 +370,100 @@ Building the Doxygen documentation is pretty simple: $ ./waf doxygen -This builds using the default configuration, which generates documentation -sections for *all* items, even if they do not have explicit comment -documentation blocks. This has the effect of suppressing warnings for -undocumented items, but makes sure everything appears in the generated -output. +This builds using the default configuration, which generates +documentation sections for *all* items, even if they do not have +explicit comment documentation blocks. This has the effect of +suppressing warnings for undocumented items, but makes sure everything +appears in the generated output, which is usually what you want for +general use. Note that we generate documentation even for modules +which are disabled, to make it easier to see all the features +available in |ns3|. When writing documentation, it's often more useful to see which items -are generating warnings, typically about missing documentation. -To see the full warnings list, use the ``doc/doxygen.warnings.report.sh`` +are generating warnings, typically about missing documentation. To +see the full warnings list, use the ``doc/doxygen.warnings.report.sh`` script: .. sourcecode:: bash - $ doc/doxygen.warnings.report.sh - Waf: Entering directory `build' - ... - Waf: Leaving directory `build' - 'build' finished successfully (3m24.094s) - - Rebuilding doxygen docs with full errors...Done. + $ doc/doxygen.warnings.report.sh + + doxygen.warnings.report.sh: + Building and running print-introspected-doxygen...done. + Rebuilding doxygen (v1.8.10) docs with full errors...done. - Report of Doxygen warnings - ---------------------------------------- + Report of Doxygen warnings + ---------------------------------------- - (All counts are lower bounds.) + (All counts are lower bounds.) - Warnings by module/directory: + Warnings by module/directory: - Count Directory - ----- ---------------------------------- - 3844 src/lte/model - 1718 src/wimax/model - 1423 src/core/model - .... - 138 additional undocumented parameters. - ---------------------------------------- - 15765 total warnings - 126 directories with warnings + Count Directory + ----- ---------------------------------- + 3414 src/lte/model + 1532 src/wimax/model + 825 src/lte/test + .... + 1 src/applications/test + 97 additional undocumented parameters. + ---------------------------------------- + 12460 total warnings + 100 directories with warnings - Warnings by file (alphabetical) + Warnings by file (alphabetical) - Count File - ----- ---------------------------------- - 17 doc/introspected-doxygen.h - 15 examples/routing/manet-routing-compare.cc - 26 examples/stats/wifi-example-apps.h - .... - ---------------------------------------- - 967 files with warnings + Count File + ----- ---------------------------------- + 15 examples/routing/manet-routing-compare.cc + 26 examples/stats/wifi-example-apps.h + 12 examples/tutorial/fifth.cc + .... + 17 utils/python-unit-tests.py + ---------------------------------------- + 771 files with warnings - Warnings by file (numerical) + Warnings by file (numerical) - Count File - ----- ---------------------------------- - 374 src/lte/model/lte-asn1-header.h - 280 src/lte/model/lte-rrc-sap.h - 262 src/lte/model/lte-rrc-header.h - .... - ---------------------------------------- - 967 files with warnings + Count File + ----- ---------------------------------- + 273 src/lte/model/lte-rrc-sap.h + 272 src/core/model/simulator.h + 221 src/netanim/model/animation-interface.h + .... + 1 src/wimax/model/ul-job.cc + ---------------------------------------- + 771 files with warnings - Doxygen Warnings Summary - ---------------------------------------- - 126 directories - 967 files - 15765 warnings + Doxygen Warnings Summary + ---------------------------------------- + 100 directories + 771 files + 12460 warnings -The script modifies the configuration to show all warnings, and -to shorten the run time. As you can see, at this writing we have -*a lot* of undocumented items. The report summarizes warnings -by module ``src/*/*``, and by file, in alphabetically and numerical -order. +(This snippet has *a lot* of lines suppressed!) -The script has a few options to pare things down and make this more +The script modifies the configuration to show all warnings, and to +shorten the run time. (It shortens the run time primarily by +disabling creation of diagrams, such as call trees, and doesn't +generate documentation for undocumented items, in order to trigger the +warnings.) As you can see, at this writing we have *a lot* of +undocumented items. The report summarizes warnings by module +``src/*/*``, and by file, in alphabetically and numerical order. + +The script has a few options to pare things down and make the output more manageable. For help, use the ``-h`` option. Having run it once to do the Doxygen build and generate the full warnings log, you can reprocess the log file with various "filters," -without having to do the full Doxygen build by, -again using the ``-s`` option. You can exclude warnings +without having to do the full Doxygen build again by +using the ``-s`` option. You can exclude warnings from ``*/examples/*`` files (``-e`` option), and/or ``*/test/*`` files -(``-t``). +(``-t``). Just to be clear, all of the filter options do the complete +fast doxygen build; they just filter doxygen log and warnings output. Perhaps the most useful option when writing documentation comments is ``-m ``, which will limit the report to just files matching @@ -486,6 +497,13 @@ urgent in a single module: src/mesh/helper/mesh-helper.h:119: warning: parameters of member ns3::MeshHelper::SetStandard are not (all) documented +Finally, note that undocumented items (classes, methods, functions, +typedefs, *etc.* won't produce documentation when you build with +``doxygen.warnings.report.sh``, and only the outermost item +will produce a warning. As a result, if you don't see documentation +for a class method in the generated documentation, the class itself +probably needs documentation. + Now it's just a matter of understanding the code, and writing some docs! @@ -508,24 +526,45 @@ usage for |ns3|. /** * \defgroup foo Foo protocol. + * Implemenation of the Foo protocol. */ - Mark each associated class as belonging to the group:: + The symbol ``foo`` is how other items can add themselves to this group. + The string following that will be the title for the group. Any futher + text will be the detailed descriptionf for the group page. + +* Document each file, assigning it to the relevant group. In a header file:: + + /** + * \file + * \ingroup foo + * Class Foo declaration. + */ + + or in the corresponding ``.cc`` file:: + + /** + * \file + * \ingroup foo + * Class FooBar implementation. + */ + +* Mark each associated class as belonging to the group:: /** * \ingroup foo * - * Foo packet type. + * FooBar packet type. */ - class Foo + class FooBar * Did you know ``typedefs`` can have formal arguments? This enables documentation of function pointer signatures:: /** - * Bar callback function signature. + * Bar callback function signature. * - * \param ale The size of a pint of ale, in Imperial ounces. + * \param ale The size of a pint of ale, in Imperial ounces. */ typedef void (* BarCallback)(const int ale); @@ -534,12 +573,32 @@ usage for |ns3|. * ``\bugid{298}`` will create a link to bug 298 in our Bugzilla. -* ``\pname{foo}`` in a description will format ``foo`` - as a ``\param foo`` parameter, making it clear that you +* ``\p foo`` in a description will format ``foo`` + the same as the ``\param foo`` parameter, making it clear that you are referring to an actual argument. * ``\RFC{301}`` will create a link to RFC 301. +* Document the direction of function arguments with ``\param [in]``, _etc_. + The allowed values of the direction token are ``[in]``, ``[out]``, and + ``[in,out]`` (note the explicit square brackets), as discussed in the + Doxygen docs for ``\param``. + +* Document template arguments with ``\tparam``, just as you use ``\param`` + for function arguments. + +* For template arguments, indicate if they will be deduced or must be given + explicitly:: + + template void Function (U a); + + * Use ``\tparam U \deduced`` because the type ``U`` can be deduced at + the site where the template is invoked. Basically deduction can only + be done for function arguments. + + * Use ``\tparam T \explicit`` because the type ``T`` can't be deduced; + it must be given explicitly at the invocation site. + * ``\internal`` should be used only to set off a discussion of implementation details, not to mark ``private`` functions (they are already marked, as ``private``!) diff --git a/src/core/model/attribute-accessor-helper.h b/src/core/model/attribute-accessor-helper.h index 54d0a92a1..025251253 100644 --- a/src/core/model/attribute-accessor-helper.h +++ b/src/core/model/attribute-accessor-helper.h @@ -56,10 +56,11 @@ namespace ns3 { * In the case of a \p setter returning \p bool, the return value * should be \c true if the value could be set successfully. * - * \tparam V (If present) The specific AttributeValue type to use to represent - * the Attribute. (If not present, the type \p V is implicit - * in the name of this function as "MakeAccessor" - * \tparam T1 The type of the class data member, + * \tparam V \explicit (If present) The specific AttributeValue type + * to use to represent the Attribute. (If not present, + * the type \p V is implicit in the name of this function, + * as "MakeAccessor" + * \tparam T1 \deduced The type of the class data member, * or the type of the class get functor or set method. * \param a1 The address of the data member, * or the get or set method. @@ -99,13 +100,13 @@ MakeAccessorHelper (T1 a1); * In practice the setter and getter arguments can appear in either order, * but setter first is preferred. * - * \tparam V (If present) The specific AttributeValue type to use to represent + * \tparam V \explicit (If present) The specific AttributeValue type to use to represent * the Attribute. (If not present, the type \p V is implicit * in the name of this function as "MakeAccessor" - * \tparam T1 The type of the class data member, + * \tparam T1 \deduced The type of the class data member, * or the type of the class get functor or set method. * - * \tparam T2 The type of the getter class functor method. + * \tparam T2 \deduced The type of the getter class functor method. * \param a2 The address of the class method to set the attribute. * \param a1 The address of the data member, * or the get or set method. @@ -134,7 +135,7 @@ namespace ns3 { * * The non-const and non-reference type equivalent to \p T. * - * \tparam T The original (possibly qualified) type. + * \tparam T \explicit The original (possibly qualified) type. */ template struct AccessorTrait @@ -150,8 +151,8 @@ struct AccessorTrait * Basic functionality for accessing class attributes via * class data members, or get functor/set methods. * - * \tparam T Class of object holding the attribute. - * \tparam U AttributeValue type for the underlying class member + * \tparam T \explicit Class of object holding the attribute. + * \tparam U \explicit AttributeValue type for the underlying class member * which is an attribute. */ template @@ -241,10 +242,10 @@ private: * * MakeAccessorHelper implementation for a class data member. * - * \tparam V The specific AttributeValue type to use to represent + * \tparam V \explicit The specific AttributeValue type to use to represent * the Attribute. - * \tparam T The class holding the data member. - * \tparam U The type of the data member. + * \tparam T \deduced The class holding the data member. + * \tparam U \deduced The type of the data member. * \param memberVariable The address of the data member. * \returns The AttributeAccessor. */ @@ -298,10 +299,10 @@ private: * * MakeAccessorHelper implementation for a class get functor method. * - * \tparam V The specific AttributeValue type to use to represent + * \tparam V \explicit The specific AttributeValue type to use to represent * the Attribute. - * \tparam T The class holding the get functor method. - * \tparam U The return type of the get functor method. + * \tparam T \deduced The class holding the get functor method. + * \tparam U \deduced The return type of the get functor method. * \param getter The address of the class get functor method. * \returns The AttributeAccessor. */ @@ -348,10 +349,10 @@ private: * MakeAccessorHelper implementation for a class set method * returning void. * - * \tparam V The specific AttributeValue type to use to represent + * \tparam V \explicit The specific AttributeValue type to use to represent * the Attribute. - * \tparam T The class holding the set method. - * \tparam U The argument type of the set method. + * \tparam T \deduced The class holding the set method. + * \tparam U \deduced The argument type of the set method. * \param setter The address of the class set method, returning void. * \returns The AttributeAccessor. */ @@ -406,11 +407,11 @@ private: * * The two versions of this function differ only in argument order. * - * \tparam W The specific AttributeValue type to use to represent + * \tparam W \explicit The specific AttributeValue type to use to represent * the Attribute. - * \tparam T The class holding the functor methods. - * \tparam U The argument type of the set method. - * \tparam V The return type of the get functor method. + * \tparam T \deduced The class holding the functor methods. + * \tparam U \deduced The argument type of the set method. + * \tparam V \deduced The return type of the get functor method. * \param setter The address of the class set method, returning void. * \param getter The address of the class get functor method. * \returns The AttributeAccessor. @@ -489,11 +490,11 @@ DoMakeAccessorHelperTwo (V (T::*getter)(void) const, * * The two versions of this function differ only in argument order. * - * \tparam W The specific AttributeValue type to use to represent + * \tparam W \explicit The specific AttributeValue type to use to represent * the Attribute. - * \tparam T The class holding the functor methods. - * \tparam U The argument type of the set method. - * \tparam V The return type of the get functor method. + * \tparam T \deduced The class holding the functor methods. + * \tparam U \deduced The argument type of the set method. + * \tparam V \deduced The return type of the get functor method. * \param setter The address of the class set method, returning bool. * \param getter The address of the class get functor method. * \returns The AttributeAccessor. diff --git a/src/core/model/attribute-helper.h b/src/core/model/attribute-helper.h index 7b9f2c473..bd720080c 100644 --- a/src/core/model/attribute-helper.h +++ b/src/core/model/attribute-helper.h @@ -85,12 +85,12 @@ namespace ns3 { * * A simple string-based attribute checker * - * \tparam T The specific AttributeValue type used to represent + * \tparam T \explicit The specific AttributeValue type used to represent * the Attribute. - * \tparam BASE The AttributeChecker type corresponding to \p T. - * \param name The name of the AttributeValue type, essentially the + * \tparam BASE \explicit The AttributeChecker type corresponding to \p T. + * \param [in] name The name of the AttributeValue type, essentially the * string form of \p T. - * \param underlying Underlying type name. + * \param [in] underlying Underlying type name. * \return Ptr to AttributeChecker. */ template diff --git a/src/core/model/default-deleter.h b/src/core/model/default-deleter.h index a4662e6a5..fcb66b4cd 100644 --- a/src/core/model/default-deleter.h +++ b/src/core/model/default-deleter.h @@ -35,7 +35,7 @@ namespace ns3 { * last reference to an object they manage * disappears. * - * \tparam T The object type being deleted. + * \tparam T \deduced The object type being deleted. * \sa ns3::SimpleRefCount */ template @@ -46,7 +46,7 @@ struct DefaultDeleter * \code * delete object; * \endcode - * \tparam T The object type being deleted. + * \tparam T \deduced The object type being deleted. * \param [in] object The object to delete. */ inline static void Delete (T *object) { diff --git a/src/core/model/int-to-type.h b/src/core/model/int-to-type.h index 77cfe6314..e7edb7559 100644 --- a/src/core/model/int-to-type.h +++ b/src/core/model/int-to-type.h @@ -36,7 +36,7 @@ namespace ns3 { * * For an example, see timer-impl.h * - * \tparam v The integral constant value distinguishing this type + * \tparam v \explicit The integral constant value distinguishing this type * from other values. */ template diff --git a/src/core/model/make-event.h b/src/core/model/make-event.h index d02fa3a83..3ce3217c0 100644 --- a/src/core/model/make-event.h +++ b/src/core/model/make-event.h @@ -45,8 +45,8 @@ class EventImpl; * Make an EventImpl from class method members which take * varying numbers of arguments. * - * \tparam MEM The class method function signature. - * \tparam OBJ The class type holding the method. + * \tparam MEM \deduced The class method function signature. + * \tparam OBJ \deduced The class type holding the method. * \param mem_ptr Class method member function pointer * \param obj Class instance. * \returns The constructed EventImpl. @@ -56,9 +56,9 @@ EventImpl * MakeEvent (MEM mem_ptr, OBJ obj); /** * \copybrief MakeEvent(MEM,OBJ) - * \tparam MEM The class method function signature. - * \tparam OBJ The class type holding the method. - * \tparam T1 Type of the argument to the underlying function. + * \tparam MEM \deduced The class method function signature. + * \tparam OBJ \deduced The class type holding the method. + * \tparam T1 \deduced Type of the argument to the underlying function. * \param mem_ptr Class method member function pointer * \param obj Class instance. * \param a1 Argument value to be bound to the underlying function. @@ -70,10 +70,10 @@ EventImpl * MakeEvent (MEM mem_ptr, OBJ obj, T1 a1); /** * \copybrief MakeEvent(MEM,OBJ) - * \tparam MEM The class method function signature. - * \tparam OBJ The class type holding the method. - * \tparam T1 Type of the first argument to the underlying function. - * \tparam T2 Type of the second argument to the underlying function. + * \tparam MEM \deduced The class method function signature. + * \tparam OBJ \deduced The class type holding the method. + * \tparam T1 \deduced Type of the first argument to the underlying function. + * \tparam T2 \deduced Type of the second argument to the underlying function. * \param mem_ptr Class method member function pointer * \param obj Class instance. * \param a1 First argument value to be bound to the underlying function. @@ -86,11 +86,11 @@ EventImpl * MakeEvent (MEM mem_ptr, OBJ obj, T1 a1, T2 a2); /** * \copybrief MakeEvent(MEM,OBJ) - * \tparam MEM The class method function signature. - * \tparam OBJ The class type holding the method. - * \tparam T1 Type of the first argument to the underlying function. - * \tparam T2 Type of the second argument to the underlying function. - * \tparam T3 Type of the third argument to the underlying function. + * \tparam MEM \deduced The class method function signature. + * \tparam OBJ \deduced The class type holding the method. + * \tparam T1 \deduced Type of the first argument to the underlying function. + * \tparam T2 \deduced Type of the second argument to the underlying function. + * \tparam T3 \deduced Type of the third argument to the underlying function. * \param mem_ptr Class method member function pointer * \param obj Class instance. * \param a1 First argument value to be bound to the underlying function. @@ -104,12 +104,12 @@ EventImpl * MakeEvent (MEM mem_ptr, OBJ obj, T1 a1, T2 a2, T3 a3); /** * \copybrief MakeEvent(MEM,OBJ) - * \tparam MEM The class method function signature. - * \tparam OBJ The class type holding the method. - * \tparam T1 Type of the first argument to the underlying function. - * \tparam T2 Type of the second argument to the underlying function. - * \tparam T3 Type of the third argument to the underlying function. - * \tparam T4 Type of the fourth argument to the underlying function. + * \tparam MEM \deduced The class method function signature. + * \tparam OBJ \deduced The class type holding the method. + * \tparam T1 \deduced Type of the first argument to the underlying function. + * \tparam T2 \deduced Type of the second argument to the underlying function. + * \tparam T3 \deduced Type of the third argument to the underlying function. + * \tparam T4 \deduced Type of the fourth argument to the underlying function. * \param mem_ptr Class method member function pointer * \param obj Class instance. * \param a1 First argument value to be bound to the underlying function. @@ -124,13 +124,13 @@ EventImpl * MakeEvent (MEM mem_ptr, OBJ obj, T1 a1, T2 a2, T3 a3, T4 a4); /** * \copybrief MakeEvent(MEM,OBJ) - * \tparam MEM The class method function signature. - * \tparam OBJ The class type holding the method. - * \tparam T1 Type of the first argument to the underlying function. - * \tparam T2 Type of the second argument to the underlying function. - * \tparam T3 Type of the third argument to the underlying function. - * \tparam T4 Type of the fourth argument to the underlying function. - * \tparam T5 Type of the fifth argument to the underlying function. + * \tparam MEM \deduced The class method function signature. + * \tparam OBJ \deduced The class type holding the method. + * \tparam T1 \deduced Type of the first argument to the underlying function. + * \tparam T2 \deduced Type of the second argument to the underlying function. + * \tparam T3 \deduced Type of the third argument to the underlying function. + * \tparam T4 \deduced Type of the fourth argument to the underlying function. + * \tparam T5 \deduced Type of the fifth argument to the underlying function. * \param mem_ptr Class method member function pointer * \param obj Class instance. * \param a1 First argument value to be bound to the underlying function. @@ -166,8 +166,8 @@ EventImpl * MakeEvent (void (*f)(void)); /** * \copybrief MakeEvent(void(*f)(void)) - * \tparam U1 Formal type of the argument to the function. - * \tparam T1 Actual type of the argument to the function. + * \tparam U1 \deduced Formal type of the argument to the function. + * \tparam T1 \deduced Actual type of the argument to the function. * \param f The function pointer. * \param a1 Argument to be bound to the function. * \returns The constructed EventImpl. @@ -178,10 +178,10 @@ EventImpl * MakeEvent (void (*f)(U1), T1 a1); /** * \copybrief MakeEvent(void(*f)(void)) - * \tparam U1 Formal type of the first argument to the function. - * \tparam U2 Formal type of the second argument to the function. - * \tparam T1 Actual type of the first argument to the function. - * \tparam T2 Actual type of the second argument to the function. + * \tparam U1 \deduced Formal type of the first argument to the function. + * \tparam U2 \deduced Formal type of the second argument to the function. + * \tparam T1 \deduced Actual type of the first argument to the function. + * \tparam T2 \deduced Actual type of the second argument to the function. * \param f The function pointer. * \param a1 First argument to be bound to the function. * \param a2 Second argument to be bound to the function. @@ -193,12 +193,12 @@ EventImpl * MakeEvent (void (*f)(U1,U2), T1 a1, T2 a2); /** * \copybrief MakeEvent(void(*f)(void)) - * \tparam U1 Formal type of the first argument to the function. - * \tparam U2 Formal type of the second argument to the function. - * \tparam U3 Formal type of the third argument to the function. - * \tparam T1 Actual type of the first argument to the function. - * \tparam T2 Actual type of the second argument to the function. - * \tparam T3 Actual type of the third argument to the function. + * \tparam U1 \deduced Formal type of the first argument to the function. + * \tparam U2 \deduced Formal type of the second argument to the function. + * \tparam U3 \deduced Formal type of the third argument to the function. + * \tparam T1 \deduced Actual type of the first argument to the function. + * \tparam T2 \deduced Actual type of the second argument to the function. + * \tparam T3 \deduced Actual type of the third argument to the function. * \param f The function pointer. * \param a1 First argument to be bound to the function. * \param a2 Second argument to be bound to the function. @@ -211,14 +211,14 @@ EventImpl * MakeEvent (void (*f)(U1,U2,U3), T1 a1, T2 a2, T3 a3); /** * \copybrief MakeEvent(void(*f)(void)) - * \tparam U1 Formal type of the first argument to the function. - * \tparam U2 Formal type of the second argument to the function. - * \tparam U3 Formal type of the third argument to the function. - * \tparam U4 Formal type of the fourth argument to the function. - * \tparam T1 Actual type of the first argument to the function. - * \tparam T2 Actual type of the second argument to the function. - * \tparam T3 Actual type of the third argument to the function. - * \tparam T4 Actual type of the fourth argument to the function. + * \tparam U1 \deduced Formal type of the first argument to the function. + * \tparam U2 \deduced Formal type of the second argument to the function. + * \tparam U3 \deduced Formal type of the third argument to the function. + * \tparam U4 \deduced Formal type of the fourth argument to the function. + * \tparam T1 \deduced Actual type of the first argument to the function. + * \tparam T2 \deduced Actual type of the second argument to the function. + * \tparam T3 \deduced Actual type of the third argument to the function. + * \tparam T4 \deduced Actual type of the fourth argument to the function. * \param f The function pointer. * \param a1 First argument to be bound to the function. * \param a2 Second argument to be bound to the function. @@ -232,16 +232,16 @@ EventImpl * MakeEvent (void (*f)(U1,U2,U3,U4), T1 a1, T2 a2, T3 a3, T4 a4); /** * \copybrief MakeEvent(void(*f)(void)) - * \tparam U1 Formal type of the first argument to the function. - * \tparam U2 Formal type of the second argument to the function. - * \tparam U3 Formal type of the third argument to the function. - * \tparam U4 Formal type of the fourth argument to the function. - * \tparam U5 Formal type of the fifth argument to the function. - * \tparam T1 Actual type of the first argument to the function. - * \tparam T2 Actual type of the second argument to the function. - * \tparam T3 Actual type of the third argument to the function. - * \tparam T4 Actual type of the fourth argument to the function. - * \tparam T5 Actual type of the fifth argument to the function. + * \tparam U1 \deduced Formal type of the first argument to the function. + * \tparam U2 \deduced Formal type of the second argument to the function. + * \tparam U3 \deduced Formal type of the third argument to the function. + * \tparam U4 \deduced Formal type of the fourth argument to the function. + * \tparam U5 \deduced Formal type of the fifth argument to the function. + * \tparam T1 \deduced Actual type of the first argument to the function. + * \tparam T2 \deduced Actual type of the second argument to the function. + * \tparam T3 \deduced Actual type of the third argument to the function. + * \tparam T4 \deduced Actual type of the fourth argument to the function. + * \tparam T5 \deduced Actual type of the fifth argument to the function. * \param f The function pointer. * \param a1 First argument to be bound to the function. * \param a2 Second argument to be bound to the function. @@ -274,7 +274,7 @@ namespace ns3 { * * This is the generic template declaration (with empty body). * - * \tparam T The class type. + * \tparam T \explicit The class type. */ template struct EventMemberImplObjTraits; @@ -287,7 +287,7 @@ struct EventMemberImplObjTraits; * * This is the specialization for pointer types. * - * \tparam T The class type. + * \tparam T \explicit The class type. */ template struct EventMemberImplObjTraits diff --git a/src/core/model/object-factory.h b/src/core/model/object-factory.h index c16efde4f..040b0b827 100644 --- a/src/core/model/object-factory.h +++ b/src/core/model/object-factory.h @@ -99,7 +99,7 @@ public: * returning a pointer of the requested type to the user. This method * is really syntactical sugar. * - * \tparam T The requested Object type. + * \tparam T \explicit The requested Object type. * \returns A new object instance. */ template @@ -146,7 +146,7 @@ std::istream & operator >> (std::istream &is, ObjectFactory &factory); * \ingroup object * Allocate an Object on the heap and initialize with a set of attributes. * - * \tparam T The requested Object type. + * \tparam T \explicit The requested Object type. * \param n1 Name of attribute * \param v1 Value of attribute * \param n2 Name of attribute diff --git a/src/core/model/object-ptr-container.h b/src/core/model/object-ptr-container.h index b2f219eff..8d4493308 100644 --- a/src/core/model/object-ptr-container.h +++ b/src/core/model/object-ptr-container.h @@ -113,9 +113,9 @@ private: * * The two versions of this function differ only in argument order. * - * \tparam T The container class type. - * \tparam U The type of object the get method returns. - * \tparam INDEX The type of the index variable. + * \tparam T \deduced The container class type. + * \tparam U \deduced The type of object the get method returns. + * \tparam INDEX \deduced The type of the index variable. * \param [in] get The class method to get a specific instance * from the container. * \param [in] getN The class method to return the number of objects @@ -133,9 +133,9 @@ MakeObjectPtrContainerAccessor (Ptr (T::*get)(INDEX) const, * * The two versions of this function differ only in argument order. * - * \tparam T The container class type. - * \tparam U The type of object the get method returns. - * \tparam INDEX The type of the index variable. + * \tparam T \deduced The container class type. + * \tparam U \deduced The type of object the get method returns. + * \tparam INDEX \deduced The type of the index variable. * \param [in] get The class method to get a specific instance * from the container. * \param [in] getN The class method to return the number of objects diff --git a/src/core/model/object.h b/src/core/model/object.h index 15f1cf3b1..72f435fff 100644 --- a/src/core/model/object.h +++ b/src/core/model/object.h @@ -305,7 +305,7 @@ private: /** * Set the TypeId and construct all Attributes of an Object. * - * \tparam T The type of the derived object we are constructing. + * \tparam T \explicit The type of the derived object we are constructing. * \param [in] object The uninitialized object pointer. * \return The derived object. */ @@ -517,7 +517,7 @@ Ptr CompleteConstruct (T *object) /** * Create an object by type, with varying number of constructor parameters. * - * \tparam T The type of the derived object to construct. + * \tparam T \explicit The type of the derived object to construct. * \return The derived object. */ template @@ -527,8 +527,8 @@ Ptr CreateObject (void) } /** * \copybrief CreateObject() - * \tparam T The type of the derived object to construct. - * \tparam T1 The type of the constructor argument. + * \tparam T \explicit The type of the derived object to construct. + * \tparam T1 \deduced The type of the constructor argument. * \param a1 The constructor argument * \return The derived object. */ @@ -540,9 +540,9 @@ Ptr CreateObject (T1 a1) /** * \copybrief CreateObject() - * \tparam T The type of the derived object to construct. - * \tparam T1 The type of the first constructor argument. - * \tparam T2 The type of the second constructor argument. + * \tparam T \explicit The type of the derived object to construct. + * \tparam T1 \deduced The type of the first constructor argument. + * \tparam T2 \deduced The type of the second constructor argument. * \param a1 The constructor first argument * \param a2 The constructor second argument * \return The derived object. @@ -555,10 +555,10 @@ Ptr CreateObject (T1 a1, T2 a2) /** * \copybrief CreateObject() - * \tparam T The type of the derived object to construct. - * \tparam T1 The type of the first constructor argument. - * \tparam T2 The type of the second constructor argument. - * \tparam T3 The type of the third constructor argument. + * \tparam T \explicit The type of the derived object to construct. + * \tparam T1 \deduced The type of the first constructor argument. + * \tparam T2 \deduced The type of the second constructor argument. + * \tparam T3 \deduced The type of the third constructor argument. * \param a1 The constructor first argument * \param a2 The constructor second argument * \param a3 The constructor third argument @@ -572,11 +572,11 @@ Ptr CreateObject (T1 a1, T2 a2, T3 a3) /** * \copybrief CreateObject() - * \tparam T The type of the derived object to construct. - * \tparam T1 The type of the first constructor argument. - * \tparam T2 The type of the second constructor argument. - * \tparam T3 The type of the third constructor argument. - * \tparam T4 The type of the fourth constructor argument. + * \tparam T \explicit The type of the derived object to construct. + * \tparam T1 \deduced The type of the first constructor argument. + * \tparam T2 \deduced The type of the second constructor argument. + * \tparam T3 \deduced The type of the third constructor argument. + * \tparam T4 \deduced The type of the fourth constructor argument. * \param a1 The constructor first argument * \param a2 The constructor second argument * \param a3 The constructor third argument @@ -591,12 +591,12 @@ Ptr CreateObject (T1 a1, T2 a2, T3 a3, T4 a4) /** * \copybrief CreateObject() - * \tparam T The type of the derived object to construct. - * \tparam T1 The type of the first constructor argument. - * \tparam T2 The type of the second constructor argument. - * \tparam T3 The type of the third constructor argument. - * \tparam T4 The type of the fourth constructor argument. - * \tparam T5 The type of the fifth constructor argument. + * \tparam T \explicit The type of the derived object to construct. + * \tparam T1 \deduced The type of the first constructor argument. + * \tparam T2 \deduced The type of the second constructor argument. + * \tparam T3 \deduced The type of the third constructor argument. + * \tparam T4 \deduced The type of the fourth constructor argument. + * \tparam T5 \deduced The type of the fifth constructor argument. * \param a1 The constructor first argument * \param a2 The constructor second argument * \param a3 The constructor third argument @@ -612,13 +612,13 @@ Ptr CreateObject (T1 a1, T2 a2, T3 a3, T4 a4, T5 a5) /** * \copybrief CreateObject() - * \tparam T The type of the derived object to construct. - * \tparam T1 The type of the first constructor argument. - * \tparam T2 The type of the second constructor argument. - * \tparam T3 The type of the third constructor argument. - * \tparam T4 The type of the fourth constructor argument. - * \tparam T5 The type of the fifth constructor argument. - * \tparam T6 The type of the sixth constructor argument. + * \tparam T \explicit The type of the derived object to construct. + * \tparam T1 \deduced The type of the first constructor argument. + * \tparam T2 \deduced The type of the second constructor argument. + * \tparam T3 \deduced The type of the third constructor argument. + * \tparam T4 \deduced The type of the fourth constructor argument. + * \tparam T5 \deduced The type of the fifth constructor argument. + * \tparam T6 \deduced The type of the sixth constructor argument. * \param a1 The constructor first argument * \param a2 The constructor second argument * \param a3 The constructor third argument @@ -635,14 +635,14 @@ Ptr CreateObject (T1 a1, T2 a2, T3 a3, T4 a4, T5 a5, T6 a6) /** * \copybrief CreateObject() - * \tparam T The type of the derived object to construct. - * \tparam T1 The type of the first constructor argument. - * \tparam T2 The type of the second constructor argument. - * \tparam T3 The type of the third constructor argument. - * \tparam T4 The type of the fourth constructor argument. - * \tparam T5 The type of the fifth constructor argument. - * \tparam T6 The type of the sixth constructor argument. - * \tparam T7 The type of the seventh constructor argument. + * \tparam T \explicit The type of the derived object to construct. + * \tparam T1 \deduced The type of the first constructor argument. + * \tparam T2 \deduced The type of the second constructor argument. + * \tparam T3 \deduced The type of the third constructor argument. + * \tparam T4 \deduced The type of the fourth constructor argument. + * \tparam T5 \deduced The type of the fifth constructor argument. + * \tparam T6 \deduced The type of the sixth constructor argument. + * \tparam T7 \deduced The type of the seventh constructor argument. * \param a1 The constructor first argument * \param a2 The constructor second argument * \param a3 The constructor third argument diff --git a/src/core/model/pointer.h b/src/core/model/pointer.h index 785fef5c2..207f2588a 100644 --- a/src/core/model/pointer.h +++ b/src/core/model/pointer.h @@ -61,13 +61,16 @@ public: /** * Construct this PointerValue by referencing an explicit Object. * - * \tparam T (implicit) The type of the object. + * \tparam T \deduced The type of the object. * \param [in] object The object to begin with. */ template PointerValue (const Ptr & object); - /** Cast to an Object of type \c T. */ + /** + * Cast to an Object of type \c T. + * \tparam T \explicit The type to cast to. + */ template operator Ptr () const; @@ -75,6 +78,7 @@ public: template void Set (const Ptr & value); + /** \tparam T \explicit The type to cast to. */ template Ptr Get (void) const; @@ -100,6 +104,12 @@ public: */ virtual TypeId GetPointeeTypeId (void) const = 0; }; + +/** + * Create a PointerChecker for a type. + * \tparam T \explicit The underlying type. + * \returns The PointerChecker. + */ template Ptr MakePointerChecker (void); diff --git a/src/core/model/ptr.h b/src/core/model/ptr.h index 00de5f697..bbb4f9ce4 100644 --- a/src/core/model/ptr.h +++ b/src/core/model/ptr.h @@ -67,7 +67,7 @@ namespace ns3 { * functions and their goal is just is save you a small * bit of typing. * - * \tparam T The underlying type. + * \tparam T \explicit The underlying type. */ template class Ptr @@ -147,7 +147,7 @@ public: /** * Copy, removing \c const qualifier. * - * \tparam U The underlying type of the \c const object. + * \tparam U \deduced The underlying type of the \c const object. * \param [in] o The Ptr to copy. */ template @@ -216,15 +216,15 @@ public: */ /** @{ */ /** - * \tparam T The type of class object to create. + * \tparam T \explicit The type of class object to create. * \return A Ptr to the newly created \c T. */ template Ptr Create (void); /** - * \tparam T The type of class object to create. - * \tparam T1 The type of the first constructor argument. + * \tparam T \explicit The type of class object to create. + * \tparam T1 \deduced The type of the first constructor argument. * \param a1 The first constructor argument. * \return A Ptr to the newly created \c T. */ @@ -233,9 +233,9 @@ template Create (T1 a1); /** - * \tparam T The type of class object to create. - * \tparam T1 The type of the first constructor argument. - * \tparam T2 The type of the second constructor argument. + * \tparam T \explicit The type of class object to create. + * \tparam T1 \deduced The type of the first constructor argument. + * \tparam T2 \deduced The type of the second constructor argument. * \param a1 The first constructor argument. * \param a2 The second constructor argument. * \return A Ptr to the newly created \c T. @@ -245,10 +245,10 @@ template Create (T1 a1, T2 a2); /** - * \tparam T The type of class object to create. - * \tparam T1 The type of the first constructor argument. - * \tparam T2 The type of the second constructor argument. - * \tparam T3 The type of the third constructor argument. + * \tparam T \explicit The type of class object to create. + * \tparam T1 \deduced The type of the first constructor argument. + * \tparam T2 \deduced The type of the second constructor argument. + * \tparam T3 \deduced The type of the third constructor argument. * \param a1 The first constructor argument. * \param a2 The second constructor argument. * \param a3 The third constructor argument. @@ -260,11 +260,11 @@ template Create (T1 a1, T2 a2, T3 a3); /** - * \tparam T The type of class object to create. - * \tparam T1 The type of the first constructor argument. - * \tparam T2 The type of the second constructor argument. - * \tparam T3 The type of the third constructor argument. - * \tparam T4 The type of the fourth constructor argument. + * \tparam T \explicit The type of class object to create. + * \tparam T1 \deduced The type of the first constructor argument. + * \tparam T2 \deduced The type of the second constructor argument. + * \tparam T3 \deduced The type of the third constructor argument. + * \tparam T4 \deduced The type of the fourth constructor argument. * \param a1 The first constructor argument. * \param a2 The second constructor argument. * \param a3 The third constructor argument. @@ -277,12 +277,12 @@ template Create (T1 a1, T2 a2, T3 a3, T4 a4); /** - * \tparam T The type of class object to create. - * \tparam T1 The type of the first constructor argument. - * \tparam T2 The type of the second constructor argument. - * \tparam T3 The type of the third constructor argument. - * \tparam T4 The type of the fourth constructor argument. - * \tparam T5 The type of the fifth constructor argument. + * \tparam T \explicit The type of class object to create. + * \tparam T1 \deduced The type of the first constructor argument. + * \tparam T2 \deduced The type of the second constructor argument. + * \tparam T3 \deduced The type of the third constructor argument. + * \tparam T4 \deduced The type of the fourth constructor argument. + * \tparam T5 \deduced The type of the fifth constructor argument. * \param a1 The first constructor argument. * \param a2 The second constructor argument. * \param a3 The third constructor argument. @@ -297,13 +297,13 @@ template Create (T1 a1, T2 a2, T3 a3, T4 a4, T5 a5); /** - * \tparam T The type of class object to create. - * \tparam T1 The type of the first constructor argument. - * \tparam T2 The type of the second constructor argument. - * \tparam T3 The type of the third constructor argument. - * \tparam T4 The type of the fourth constructor argument. - * \tparam T5 The type of the fifth constructor argument. - * \tparam T6 The type of the sixth constructor argument. + * \tparam T \explicit The type of class object to create. + * \tparam T1 \deduced The type of the first constructor argument. + * \tparam T2 \deduced The type of the second constructor argument. + * \tparam T3 \deduced The type of the third constructor argument. + * \tparam T4 \deduced The type of the fourth constructor argument. + * \tparam T5 \deduced The type of the fifth constructor argument. + * \tparam T6 \deduced The type of the sixth constructor argument. * \param a1 The first constructor argument. * \param a2 The second constructor argument. * \param a3 The third constructor argument. @@ -319,14 +319,14 @@ template Create (T1 a1, T2 a2, T3 a3, T4 a4, T5 a5, T6 a6); /** - * \tparam T The type of class object to create. - * \tparam T1 The type of the first constructor argument. - * \tparam T2 The type of the second constructor argument. - * \tparam T3 The type of the third constructor argument. - * \tparam T4 The type of the fourth constructor argument. - * \tparam T5 The type of the fifth constructor argument. - * \tparam T6 The type of the sixth constructor argument. - * \tparam T7 The type of the seventh constructor argument. + * \tparam T \explicit The type of class object to create. + * \tparam T1 \deduced The type of the first constructor argument. + * \tparam T2 \deduced The type of the second constructor argument. + * \tparam T3 \deduced The type of the third constructor argument. + * \tparam T4 \deduced The type of the fourth constructor argument. + * \tparam T5 \deduced The type of the fifth constructor argument. + * \tparam T6 \deduced The type of the sixth constructor argument. + * \tparam T7 \deduced The type of the seventh constructor argument. * \param a1 The first constructor argument. * \param a2 The second constructor argument. * \param a3 The third constructor argument. @@ -368,8 +368,8 @@ std::ostream &operator << (std::ostream &os, const Ptr &p); * Note that either \c p or \c q could also be ordinary pointers * to the underlying object. * - * \tparam T1 Type of the object on the lhs. - * \tparam T2 Type of the object on the rhs. + * \tparam T1 \deduced Type of the object on the lhs. + * \tparam T2 \deduced Type of the object on the rhs. * \param [in] lhs The left operand. * \param [in] rhs The right operand. * \return true if the operands point to the same underlying object. @@ -399,8 +399,8 @@ bool operator == (Ptr const &lhs, Ptr const &rhs); * Note that either \c p or \c q could also be ordinary pointers * to the underlying object. * - * \tparam T1 Type of the object on the lhs. - * \tparam T2 Type of the object on the rhs. + * \tparam T1 \deduced Type of the object on the lhs. + * \tparam T2 \deduced Type of the object on the rhs. * \param [in] lhs The left operand. * \param [in] rhs The right operand. * \return true if the operands point to the same underlying object. @@ -440,8 +440,8 @@ bool operator >= (const Ptr &lhs, const Ptr &rhs); * Return a copy of \c p with its stored pointer const casted from * \c T2 to \c T1. * - * \tparam T1 The type to return in a Ptr. - * \tparam T2 The type of the underlying object. + * \tparam T1 \deduced The type to return in a Ptr. + * \tparam T2 \deduced The type of the underlying object. * \param p The original \c const Ptr. * \return A non-const Ptr. */ @@ -460,7 +460,7 @@ struct CallbackTraits; * * This is the specialization for Ptr types. * - * \tparam T The base object type. + * \tparam T \deduced The base object type. */ template struct CallbackTraits > @@ -485,7 +485,7 @@ struct EventMemberImplObjTraits; * * This is the specialization for Ptr types. * - * \tparam T The class type. + * \tparam T \explicit The class type. */ template struct EventMemberImplObjTraits > @@ -647,8 +647,8 @@ bool operator >= (const Ptr &lhs, const Ptr &rhs) /** * Cast a Ptr. * - * \tparam T1 The desired type to cast to. - * \tparam T2 The type of the original Ptr. + * \tparam T1 \deduced The desired type to cast to. + * \tparam T2 \deduced The type of the original Ptr. * \param p The original Ptr. * \return The result of the cast. */ diff --git a/src/core/model/simple-ref-count.h b/src/core/model/simple-ref-count.h index 06443a25f..6739a7b5d 100644 --- a/src/core/model/simple-ref-count.h +++ b/src/core/model/simple-ref-count.h @@ -53,17 +53,18 @@ namespace ns3 { * This template takes 3 arguments but only the first argument is * mandatory: * - * \tparam T The typename of the subclass which derives from this template - * class. Yes, this is weird but it's a common C++ template pattern - * whose name is CRTP (Curiously Recursive Template Pattern) - * \tparam PARENT: the typename of the parent of this template. By default, - * this typename is "'ns3::empty'" which is an empty class: compilers - * which implement the RBCO optimization (empty base class optimization) - * will make this a no-op - * \tparam DELETER: the typename of a class which implements a public static - * method named 'Delete'. This method will be called whenever the - * SimpleRefCount template detects that no references to the object - * it manages exist anymore. + * \tparam T \explicit The typename of the subclass which derives + * from this template class. Yes, this is weird but it's a + * common C++ template pattern whose name is CRTP (Curiously + * Recursive Template Pattern) + * \tparam PARENT \explicit The typename of the parent of this template. + * By default, this typename is "'ns3::empty'" which is an empty + * class: compilers which implement the RBCO optimization (empty + * base class optimization) will make this a no-op + * \tparam DELETER \explicit The typename of a class which implements + * a public static method named 'Delete'. This method will be called + * whenever the SimpleRefCount template detects that no references + * to the object it manages exist anymore. * * Interesting users of this class include ns3::Object as well as ns3::Packet. */ diff --git a/src/core/model/timer-impl.h b/src/core/model/timer-impl.h index ac2702c70..a747aa2cf 100644 --- a/src/core/model/timer-impl.h +++ b/src/core/model/timer-impl.h @@ -52,23 +52,23 @@ public: */ /**@{*/ /** - * \tparam T1 Type of the first argument. + * \tparam T1 \deduced Type of the first argument. * \param a1 The first argument */ template void SetArgs (T1 a1); /** - * \tparam T1 Type of the first argument. - * \tparam T2 Type of the second argument. + * \tparam T1 \deduced Type of the first argument. + * \tparam T2 \deduced Type of the second argument. * \param a1 the first argument * \param a2 the second argument */ template void SetArgs (T1 a1, T2 a2); /** - * \tparam T1 Type of the first argument. - * \tparam T2 Type of the second argument. - * \tparam T3 Type of the third argument. + * \tparam T1 \deduced Type of the first argument. + * \tparam T2 \deduced Type of the second argument. + * \tparam T3 \deduced Type of the third argument. * \param a1 the first argument * \param a2 the second argument * \param a3 the third argument @@ -76,10 +76,10 @@ public: template void SetArgs (T1 a1, T2 a2, T3 a3); /** - * \tparam T1 Type of the first argument. - * \tparam T2 Type of the second argument. - * \tparam T3 Type of the third argument. - * \tparam T4 Type of the fourth argument. + * \tparam T1 \deduced Type of the first argument. + * \tparam T2 \deduced Type of the second argument. + * \tparam T3 \deduced Type of the third argument. + * \tparam T4 \deduced Type of the fourth argument. * \param a1 the first argument * \param a2 the second argument * \param a3 the third argument @@ -89,11 +89,11 @@ public: typename T4> void SetArgs (T1 a1, T2 a2, T3 a3, T4 a4); /** - * \tparam T1 Type of the first argument. - * \tparam T2 Type of the second argument. - * \tparam T3 Type of the third argument. - * \tparam T4 Type of the fourth argument. - * \tparam T5 Type of the fifth argument. + * \tparam T1 \deduced Type of the first argument. + * \tparam T2 \deduced Type of the second argument. + * \tparam T3 \deduced Type of the third argument. + * \tparam T4 \deduced Type of the fourth argument. + * \tparam T5 \deduced Type of the fifth argument. * \param a1 the first argument * \param a2 the second argument * \param a3 the third argument @@ -104,12 +104,12 @@ public: typename T4, typename T5> void SetArgs (T1 a1, T2 a2, T3 a3, T4 a4, T5 a5); /** - * \tparam T1 Type of the first argument. - * \tparam T2 Type of the second argument. - * \tparam T3 Type of the third argument. - * \tparam T4 Type of the fourth argument. - * \tparam T5 Type of the fifth argument. - * \tparam T6 Type of the sixth argument. + * \tparam T1 \deduced Type of the first argument. + * \tparam T2 \deduced Type of the second argument. + * \tparam T3 \deduced Type of the third argument. + * \tparam T4 \deduced Type of the fourth argument. + * \tparam T5 \deduced Type of the fifth argument. + * \tparam T6 \deduced Type of the sixth argument. * \param a1 the first argument * \param a2 the second argument * \param a3 the third argument @@ -244,7 +244,7 @@ struct TimerTraits /** * Make a TimerImpl from a function pointer taking varying numbers of arguments. * - * \tparam FN Function signature type of the callback function. + * \tparam FN \deduced Function signature type of the callback function. * \param fn The function pointer to invoke when the timer expires. * \returns The TimerImpl. */ @@ -582,7 +582,7 @@ MakeTimerImpl (IntToType<6>, FN fn) * * This is the generic template declaration (with empty body). * - * \tparam T The object type. + * \tparam T \explicit The object type. */ template struct TimerImplMemberTraits; @@ -595,7 +595,7 @@ struct TimerImplMemberTraits; * * This is the specialization for pointer to \c T. * - * \tparam T The object type. + * \tparam T \explicit The object type. */ template struct TimerImplMemberTraits @@ -616,8 +616,8 @@ struct TimerImplMemberTraits * Make a TimerImpl from a class method pointer taking * a varying number of arguments. * - * \tparam MEM_PTR Class method function signature type. - * \tparam OBJ_PTR Class type. + * \tparam MEM_PTR \deduced Class method function signature type. + * \tparam OBJ_PTR \deduced Class type. * \param memPtr Class method to invoke when the timer expires. * \param objPtr Object instance pointer. * \returns The TimerImpl. diff --git a/src/core/model/trace-source-accessor.h b/src/core/model/trace-source-accessor.h index c24f751cd..a0621bbb1 100644 --- a/src/core/model/trace-source-accessor.h +++ b/src/core/model/trace-source-accessor.h @@ -128,8 +128,8 @@ namespace ns3 { * \ingroup tracing * MakeTraceSourceAccessor() implementation. * - * \tparam T Class type of the TracedCallback - * \tparam SOURCE Type of the underlying value. + * \tparam T \deduced Class type of the TracedCallback + * \tparam SOURCE \deduced Type of the underlying value. * \param a The underlying data value. * \returns The TraceSourceAccessor */ diff --git a/src/core/model/traced-callback.h b/src/core/model/traced-callback.h index 873afae55..0421471b2 100644 --- a/src/core/model/traced-callback.h +++ b/src/core/model/traced-callback.h @@ -46,14 +46,14 @@ namespace ns3 { * calling one of the \c operator() forms with the appropriate * number of arguments. * - * \tparam T1 Type of the first argument to the functor. - * \tparam T2 Type of the second argument to the functor. - * \tparam T3 Type of the third argument to the functor. - * \tparam T4 Type of the fourth argument to the functor. - * \tparam T5 Type of the fifth argument to the functor. - * \tparam T6 Type of the sixth argument to the functor. - * \tparam T7 Type of the seventh argument to the functor. - * \tparam T8 Type of the eighth argument to the functor. + * \tparam T1 \explicit Type of the first argument to the functor. + * \tparam T2 \explicit Type of the second argument to the functor. + * \tparam T3 \explicit Type of the third argument to the functor. + * \tparam T4 \explicit Type of the fourth argument to the functor. + * \tparam T5 \explicit Type of the fifth argument to the functor. + * \tparam T6 \explicit Type of the sixth argument to the functor. + * \tparam T7 \explicit Type of the seventh argument to the functor. + * \tparam T8 \explicit Type of the eighth argument to the functor. */ template > CallbackList; /** The chain of Callbacks. */ diff --git a/src/core/model/traced-value.h b/src/core/model/traced-value.h index e477c03c5..c99572cf9 100644 --- a/src/core/model/traced-value.h +++ b/src/core/model/traced-value.h @@ -73,7 +73,7 @@ namespace ns3 { * and will define Connect/DisconnectWithoutContext methods to work * with MakeTraceSourceAccessor. * - * \tparam T The type of the underlying value being traced. + * \tparam T \explicit The type of the underlying value being traced. */ template class TracedValue @@ -113,7 +113,7 @@ public: } /** * Copy from a TracedValue of a compatable type. - * \tparam U The underlying type of the other TracedValue. + * \tparam U \deduced The underlying type of the other TracedValue. * \param other The other TracedValuet to copy. */ template @@ -122,7 +122,7 @@ public: {} /** * Copy from a variable type compatible with this underlying type. - * \tparam U Type of the other variable. + * \tparam U \deduced Type of the other variable. * \param other The other variable to copy. */ template @@ -263,7 +263,7 @@ private: * * The underlying value will be written to the stream. * - * \tparam T The underlying type of the TracedValue. + * \tparam T \deduced The underlying type of the TracedValue. * \param os The output stream. * \param rhs The TracedValue to stream. * \returns The stream. @@ -276,8 +276,8 @@ std::ostream& operator << (std::ostream& os, const TracedValue& rhs) /** * Boolean operator for TracedValue. - * \tparam T The underlying type held by the left-hand argument. - * \tparam U The underlying type held by the right-hand argument. + * \tparam T \deduced The underlying type held by the left-hand argument. + * \tparam U \deduced The underlying type held by the right-hand argument. * \param lhs The left-hand argument. * \param rhs The right-hand argument. * \returns The boolean result of comparing the underlying values. @@ -418,8 +418,8 @@ bool operator > (const U &lhs, const TracedValue &rhs) * This returns the arithmetic result in a new TracedValue, * which has no Callback connected. * - * \tparam T The underlying type held by the left-hand argument. - * \tparam U The underlying type held by the right-hand argument. + * \tparam T \deduced The underlying type held by the left-hand argument. + * \tparam U \deduced The underlying type held by the right-hand argument. * \param lhs The left-hand argument. * \param rhs The right-hand argument. * \returns The result of doing the operator on @@ -621,8 +621,8 @@ TracedValue operator >> (const U &lhs, const TracedValue &rhs) { * is assigned to the \c lhs TracedValue. If the new value * is different, the Callback will be invoked. * - * \tparam T The underlying type held by the left-hand argument. - * \tparam U The underlying type held by the right-hand argument. + * \tparam T \deduced The underlying type held by the left-hand argument. + * \tparam U \deduced The underlying type held by the right-hand argument. * \param lhs The left-hand argument. * \param rhs The right-hand argument. * \returns The result of doing the operator on @@ -722,7 +722,7 @@ TracedValue &operator ^= (TracedValue &lhs, const U &rhs) { /** * Unary arithmetic operator for TracedValue. * - * \tparam T The underlying type held by the TracedValue. + * \tparam T \deduced The underlying type held by the TracedValue. * \param lhs The TracedValue. * \returns The result of doing the operator on * the underlying values. diff --git a/src/core/model/type-id.h b/src/core/model/type-id.h index 9eeca79b3..ef17aef0f 100644 --- a/src/core/model/type-id.h +++ b/src/core/model/type-id.h @@ -291,7 +291,7 @@ public: /** * Set the parent TypeId. * - * \tparam T The parent TypeID type. + * \tparam T \explicit The parent TypeID type. * \return This TypeId instance. * * Record in this TypeId which TypeId is the TypeId @@ -332,7 +332,7 @@ public: * Record in this TypeId the fact that the default constructor * is accessible. * - * \tparam T The class name represented by this TypeId. + * \tparam T \explicit The class name represented by this TypeId. * \returns This TypeId instance */ template diff --git a/src/core/model/type-name.h b/src/core/model/type-name.h index c59d11066..0c70d3e08 100644 --- a/src/core/model/type-name.h +++ b/src/core/model/type-name.h @@ -35,7 +35,7 @@ namespace ns3 { * \ingroup attributeimpl * Type name strings for numeric AttributeValue types. * - * \tparam T The numeric type. + * \tparam T \explicit The numeric type. * \returns The numeric type name as a string. */ template diff --git a/src/core/model/watchdog.h b/src/core/model/watchdog.h index d94d56c30..9f7f28cca 100644 --- a/src/core/model/watchdog.h +++ b/src/core/model/watchdog.h @@ -85,8 +85,8 @@ public: /** * Set the function to execute when the timer expires. * - * \tparam MEM_PTR Class method function type. - * \tparam OBJ_PTR Class type containing the function. + * \tparam MEM_PTR \deduced Class method function type. + * \tparam OBJ_PTR \deduced Class type containing the function. * \param memPtr The member function pointer * \param objPtr The pointer to object * @@ -101,23 +101,23 @@ public: */ /**@{*/ /** - * \tparam T1 Type of the first argument. + * \tparam T1 \deduced Type of the first argument. * \param a1 The first argument */ template void SetArguments (T1 a1); /** - * \tparam T1 Type of the first argument. - * \tparam T2 Type of the second argument. + * \tparam T1 \deduced Type of the first argument. + * \tparam T2 \deduced Type of the second argument. * \param a1 the first argument * \param a2 the second argument */ template void SetArguments (T1 a1, T2 a2); /** - * \tparam T1 Type of the first argument. - * \tparam T2 Type of the second argument. - * \tparam T3 Type of the third argument. + * \tparam T1 \deduced Type of the first argument. + * \tparam T2 \deduced Type of the second argument. + * \tparam T3 \deduced Type of the third argument. * \param a1 the first argument * \param a2 the second argument * \param a3 the third argument @@ -125,10 +125,10 @@ public: template void SetArguments (T1 a1, T2 a2, T3 a3); /** - * \tparam T1 Type of the first argument. - * \tparam T2 Type of the second argument. - * \tparam T3 Type of the third argument. - * \tparam T4 Type of the fourth argument. + * \tparam T1 \deduced Type of the first argument. + * \tparam T2 \deduced Type of the second argument. + * \tparam T3 \deduced Type of the third argument. + * \tparam T4 \deduced Type of the fourth argument. * \param a1 the first argument * \param a2 the second argument * \param a3 the third argument @@ -137,11 +137,11 @@ public: template void SetArguments (T1 a1, T2 a2, T3 a3, T4 a4); /** - * \tparam T1 Type of the first argument. - * \tparam T2 Type of the second argument. - * \tparam T3 Type of the third argument. - * \tparam T4 Type of the fourth argument. - * \tparam T5 Type of the fifth argument. + * \tparam T1 \deduced Type of the first argument. + * \tparam T2 \deduced Type of the second argument. + * \tparam T3 \deduced Type of the third argument. + * \tparam T4 \deduced Type of the fourth argument. + * \tparam T5 \deduced Type of the fifth argument. * \param a1 the first argument * \param a2 the second argument * \param a3 the third argument @@ -151,12 +151,12 @@ public: template void SetArguments (T1 a1, T2 a2, T3 a3, T4 a4, T5 a5); /** - * \tparam T1 Type of the first argument. - * \tparam T2 Type of the second argument. - * \tparam T3 Type of the third argument. - * \tparam T4 Type of the fourth argument. - * \tparam T5 Type of the fifth argument. - * \tparam T6 Type of the sixth argument. + * \tparam T1 \deduced Type of the first argument. + * \tparam T2 \deduced Type of the second argument. + * \tparam T3 \deduced Type of the third argument. + * \tparam T4 \deduced Type of the fourth argument. + * \tparam T5 \deduced Type of the fifth argument. + * \tparam T6 \deduced Type of the sixth argument. * \param a1 the first argument * \param a2 the second argument * \param a3 the third argument diff --git a/utils/print-introspected-doxygen.cc b/utils/print-introspected-doxygen.cc index 0379f163f..055d4b210 100644 --- a/utils/print-introspected-doxygen.cc +++ b/utils/print-introspected-doxygen.cc @@ -18,6 +18,12 @@ * Author: Mathieu Lacage */ +/** + * \file + * \ingroup utils + * Generate documentation from the TypeId database. + */ + #include #include #include @@ -71,6 +77,9 @@ namespace std::string sectionStart; ///< start of a section or group std::string seeAlso; ///< Reference to other docs std::string subSectionStart; ///< start a new subsection + std::string templateArgument; ///< template argument + std::string templArgExplicit; ///< template argument required + std::string templArgDeduced; ///< template argument deduced from function std::string variable; ///< variable or class member } // anonymous namespace @@ -118,6 +127,9 @@ SetMarkup (bool outputText) sectionStart = "Section "; seeAlso = " See: "; subSectionStart = "Subsection "; + templateArgument = "Template Arg: "; + templArgDeduced = "[deduced] "; + templArgExplicit = "[explicit] "; variable = "Variable: "; } else @@ -153,6 +165,9 @@ SetMarkup (bool outputText) sectionStart = "\\ingroup "; seeAlso = "\\see "; subSectionStart = "\\addtogroup "; + templateArgument = "\\tparam "; + templArgDeduced = "\\deduced "; + templArgExplicit = "\\explicit "; variable = "\\var "; } } // SetMarkup () @@ -717,6 +732,7 @@ PrintAttributeValueWithName (std::ostream & os, << functionStart << "bool" << qualClass << "::GetAccessor (T & value) const\n" << "Access the " << name << " value as type " << codeWord << "T.\n" + << templateArgument << "T " << templArgExplicit << "The type to cast to.\n" << argument << "[out] value The " << name << " value, as type " << codeWord << "T.\n" << returns << "true.\n" @@ -1116,7 +1132,7 @@ StaticInformation::Get (TypeId tid) const * The container elements must support \c operator< (for \c std::sort) * and \c operator== (for \c std::unique). * - * \tparam T The container type. + * \tparam T \deduced The container type. * \param t The container. */ template