Как документировать шаблоны С++ и метафайлы шаблонов с помощью doxygen?

Есть ли какие-либо рекомендации относительно того, как С++-шаблоны и мета-функции шаблонов должны быть документированы с помощью Doxygen?

Например:

/// @brief metafunction for generation of a map of message types to
/// their associated callbacks.
/// @tparam Seq the list of message types
template< class Seq >
struct generate_callback_map
{
    typedef typename mpl::transform< Seq
                                   , build_type_signature_pair< mpl::_1 > 
                                   >::type vector_pair_type;
    typedef typename fusion::result_of::as_map< vector_pair_type >::type type;
};

До сих пор я видел следующие предложения:

@tparam используется для документирования параметров шаблона.
@arg альтернативный способ документирования параметров шаблона.
@brief используется для описания метафокса.

Как должен быть документирован "возвращенный тип" для метафунта?

Есть ли у кого-нибудь хорошие предложения или личные предпочтения для использования Doxygen с шаблонами С++?

Ответ 1

Я не думаю, что возможно использовать расширенные конструкторы шаблонов документов с doxygen, поскольку он был первоначально разработан для объектно-ориентированной парадигмы, а не метапрограммирования. В качестве иллюстрации GNU STL (libstdС++) использует doxygen, но выполняет плохую работу для документирования метапрограмм в STL.

С другой стороны, boost использует свои собственные инструменты: QuickBook использует автономные текстовые файлы и документированный источник doxygen для генерации BoostBook (расширение DocBook), которое по очереди генерирует html/pdf. Результат более информативен, чем для libstdС++, но, очевидно, требует немного больше работы от разработчика.

Поскольку документация по заказу, возможно, одна из лучших для метапрограммирования, вы можете пройти этот маршрут, тем более, что он дополняет doxygen - вы можете повторно использовать существующую разметку.

Хотя это точно не отвечает на ваш вопрос, вы можете быть заинтересованы в последних событиях . При создании clang с помощью --with-extra-options=-Wdocumentation он семантически проверяет вашу разметку doxygen с вашим кодом и генерирует предупреждения о документации. Заставляет вас синхронизировать документы/код.

Ответ 2

Используйте аргументы @tparam template, @arg для аргументов функции. Для возвращаемых значений @return. Здесь нет возврата. Есть только typedef s.

Кстати, ваш пример кода не похож на метафунк. Метафунции - это волосатые звери, которые используют SFINAE для выполнения чего-то, чего С++ первоначально не предназначался (например, для отражения). Ваш generate_callback_map просто выглядит как С++ 03 для шаблона typedef.

Что вам не хватает, это документация по вашим typedefs и документации о том, как использовать этот шаблон.

/// @brief metafunction for generation of a map of message types to
/// their associated callbacks.
/// @details
/// Usage: Use <tt>generate_callback_map<Type>::type</tt> to ...
/// @tparam Seq the list of message types
/// 
template< class Seq >
struct generate_callback_map
{
  /// @brief It a good idea to document all of your typedefs.
  typedef typename mpl::transform< Seq
                                 , build_type_signature_pair< mpl::_1 > 
                                 >::type vector_pair_type;

  /// @brief This is why generate_callback_map exists. Document it!
  typedef typename fusion::result_of::as_map< vector_pair_type >::type type;
};