typedef in template class with Doxygen (C++)

Question

My question is related to how to comment typedef in template class with Doxygen. I will give an example to illustrate my question:

 namespace fundamental
  {
    /**
    * Basic function
    */
    template <typename T>
    class Base
    {
    public:
      T x; ///< x coordinate
      T y; ///< y coordinate
    };
    typedef Base<float> Coordinate; ///< Point coordinate class
  }

After using Doxygen to process the above codes, I can obtain a HTML page to show the definition of the class Base. However, for the typedef class Coordinate, it will not appear in the same page with Base. In fact all the typedef types are listed in the fundamental namespace page along with all the classes in this namespace. I was wondering whether it is possible to show Coordinate class in the Base HTML page. By doing so, the link between Base and Coordinate will become much closer. Thanks!

score 5 · Accepted Answer · answered Aug 07 '12 at 20:49

The typedef is part of a namespace, so you must document the namespace for it to appear, i.e.:

/// documentation for the namespace
namespace fundamental
{
   ...
   typedef Base<float> Coordinate; ///< Point coordinate class
}

Alternatively you could use @relates but it this will put the member under Related Functions of the Base class:

/// @relates Base
/// Point coordinate class
typedef Base<float> Coordinate;

You can change this title to for instance Related Members by creating a layout file using doxygen -l and then editing the two occurrences of the related element in the generated DoxygenLayout.xml as follows:

<related title="Related Members"/>

score 3 · Answer 2 · edited Mar 24 '19 at 14:49

3

In the manual I read the following:

Let's repeat that, because it is often overlooked: to document global objects (functions, typedefs, enum, macros, etc), you must document the file in which they are defined. In other words, there must at least be a

/*! \file */ or a /** @file */ line in this file.

edited Mar 24 '19 at 14:49

albert

8,285
3
19
32

answered Aug 07 '12 at 15:43

Joost Sannen

215
1
9

score 2 · Answer 3 · edited Mar 24 '19 at 18:12

2

There's the See Also (@sa) command, useful for generating cross-references to other entities.

edited Mar 24 '19 at 18:12

albert

8,285
3
19
32

answered Aug 07 '12 at 15:46

Emile Cormier

28,391
15
94
122

score 1 · Answer 4 · edited Mar 24 '19 at 17:33

1

You could also use the /sa command to manually place a reference in Base's page.

namespace fundamental
{
  /**
  * Basic function
  * /sa Coordinate
  */
  template <typename T>
  class Base
  {
  public:
    T x; ///< x coordinate
    T y; ///< y coordinate
  };
  typedef Base<float> Coordinate; ///< Point coordinate class
}

edited Mar 24 '19 at 17:33

albert

8,285
3
19
32

answered Aug 07 '12 at 15:47

Kaiged

609
1
7
19

score 0 · Answer 5 · answered Aug 07 '12 at 15:50

The other answers will work, but if your typedef is so closely tied to the Base class that you want them to appear in the same Doxygen page, you may want to consider defining a new namespace (within Fundamental) that will just include Base and your typedef. Then, doxygen will generate a page for that namespace that will include Base and your typedef.

Defining a file documentation will do the same thing, but this may be a more logical layout for your code.

score 0 · Answer 6 · edited Dec 22 '18 at 17:38

0

There is two other solutions to this problem. You can define groups using @defgroup keyword, and group the class and and typedef type into one module. The other solution is using @relates

edited Dec 22 '18 at 17:38

albert

8,285
3
19
32

answered Aug 08 '12 at 13:22

feelfree

11,175
20
96
167

typedef in template class with Doxygen (C++)

6 Answers6

Linked