typedef in template class with Doxygen (C++)

问题

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!

回答1:

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"/>

回答2:

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.

回答3:

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

回答4:

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
}

回答5:

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.

回答6:

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

来源：https://stackoverflow.com/questions/11849241/typedef-in-template-class-with-doxygen-c

标签

c++

doxygen