C语言 如何使用Doxygen编写预处理器定义相关的typedef文档?

baubqpgj  于 2023-10-16  发布在  其他
关注(0)|答案(2)|浏览(117)

是否有可能使用Doxygen在html输出中显示两种可选方式来记录依赖于预处理器定义的具有不同类型的typedef?
我想记录的代码:

/**
 * \file
 */

#ifdef _WIN32
/**
 * Documentation for Windows goes here...
 */
typedef wchar_t MyChar;
#else
/**
 * Documentation for Non-Windows goes here...
 */
typedef char MyChar;
#endif

我已经测试了几个与预处理器相关的设置,但我只能更改html输出中显示的typedef或合并文档。我甚至设法让一个typedef显示在文件的概述部分,另一个显示在详细描述部分。然而,我无法让这两种选择同时出现。
我设法产生了以下两种选择:

----------------------------------------------
typedef wchar_t   | MyChar   | ....
----------------------------------------------
----------------------------------------------
typedef char      | MyChar   | ....
----------------------------------------------

但不是这种事

----------------------------------------------
typedef wchar_t   | MyChar   | ....
----------------------------------------------
typedef char      | MyChar   | ....
----------------------------------------------

注意:我不介意修改源代码,只要

  • 在文档中,两种替代方案都合理地记录在Doxygen输出中; wchar_tchar都需要显示在typedef ...部分
  • 编译器为文件的修改版本和当前版本生成相同的结果
  • IDE自动完成,特别是Visual Studio 2019的智能感知,仍然显示合理的工具提示(可选)
camsedfj

camsedfj1#

我迟到了,但是...
如果你在Doxyfile中设置了ENABLE_PREPROCESSING = YES,然后又设置了PREDEFINED = DOXYGEN,你可以这样做:

#if defined(DOXYGEN)
    /// @brief On Windows
    typedef wchar_t MyChar;

    /// @brief On other systems
    typedef char MyChar;
#else
    #if defined(_WIN32)
        typedef wchar_t MyChar;
    #else
        typedef char MyChar;
    #endif
#endif

因此,编译器最终只看到并选择了一个定义,但Doxygen看到了两个定义并将它们添加到输出中。
您可以以降低可读性为代价来减少重复的数量:

#if defined(_WIN32) || defined(DOXYGEN)
    /// @brief On Windows
    typedef wchar_t MyChar;
#endif

#if !defined(_WIN32) || defined(DOXYGEN)
    /// @brief On other systems
    typedef char MyChar;
#endif

!与一些漂亮的大#else相比要微妙得多,但它至少意味着您不会意外地更改主代码中的定义,然后忘记更改相应的文档。
但是,如果您需要支持许多不同的操作系统,那么这很容易变成一长串过于复杂的条件。
从理论上讲,应该有一种方法可以使用\typedef命令作为显式文档的形式来实现这一点,但当我尝试时,我无法让它工作。
最后,设置ENABLE_PREPROCESSING = NO实际上可能会导致Doxygen读取:

#if defined(_WIN32)
    /// @brief On Windows
    typedef wchar_t MyChar;
#else
    /// @brief On other systems
    typedef char MyChar;
#endif

就好像它是:

/// @brief On Windows
typedef wchar_t MyChar;

/// @brief On other systems
typedef char MyChar;

但目前,这是一个未经检验的理论。
请注意,这些解决方案中的任何一个都可能最终破坏引用链接,因为当Doxygen期望每个符号都是唯一的时,您实际上定义了相同的符号两次。

ubof19bj

ubof19bj2#

不是一个真正的答案,只是一个问题/建议,以下内容是否可以接受:

/** \cond */
#ifdef _WIN32
#define used_type wchar_t
#else
#define used_type char
#endif
/** \endcond */
/**
 * Documentation for Windows goes here...
 *
 * Documentation for Non-Windows goes here...
 */
typedef used_type MyChar;

导致:

相关问题