首页 文章

如何使用doxygen记录C模板和模板元函数？

提问于
浏览 次
44

是否有关于如何使用Doxygen记录C模板和模板元函数的指南？

例如：

/// @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和C模板有任何好的建议或个人喜好？

c++ templates doxygen

2 回答

  • 36

    我不认为使用doxygen的文档高级模板构造是可能的，因为它最初是为面向对象的范例设计的，而不是元编程 . 作为一个例子，GNU STL（libstdc）使用doxygen，但是在STL中记录了元编程的_174751 .

    另一方面，boost使用自己的工具：QuickBook使用独立的文本文件和doxygen文档源生成BoostBook标记（DocBook的扩展名），然后生成html / pdf . result比libstdc更有用，但显然需要开发人员的更多工作 .

    由于boost文档可以说是最好的元编程之一，你可以走这条路，特别是因为它补充了doxygen - 你可以重用你现有的标记 .

    虽然它没有完全回答你的问题，但你可能对最近的clang developments感兴趣 . 当使用 --with-extra-options=-Wdocumentation 构建clang时，它会在语义上检查您的doxygen标记并生成文档警告 . 强制您保持文档/代码同步 .

    回复于
  • 18

    使用 @tparam 表示模板参数， @arg 表示函数参数 . 对于返回值， @return . 这里没有回报 . 只有 typedef .

    顺便说一句，您的示例代码最初并不打算做（例如，反射） . 您的 generate_callback_map 看起来像模板typedef的C 03替身 .

    您缺少的是关于typedef的文档以及有关如何使用此模板的文档 .

    /// @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's 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;
};
    回复于

相关问题