带有 C# 内部访问修饰符的 Doxygen答案

【问题标题】：Doxygen with C# internal access modifier带有 C# 内部访问修饰符的 Doxygen
【发布时间】：2010-12-24 03:43:50
【问题描述】：

我正在使用 Doxygen 为我正在处理的 C# 项目生成一些 API 文档。我在这个项目中有相当多的“内部”功能，并且不希望 Doxygen 在它生成的生成的 html 中生成这些签名。

我已尝试启用 HIDE_FRIEND_COMPOUNDS，但这仍会导致我的内部类暴露在生成的文档中。

有人知道怎么做吗？

【问题讨论】：

【解决方案1】：

添加到 Mac H 的答案，您必须设置这些额外的配置参数才能使其工作：

# The PREDEFINED tag can be used to specify one or more macro names that 
# are defined before the preprocessor is started (similar to the -D option of 
# gcc).     

PREDEFINED             = internal=private

# If the EXTRACT_PRIVATE tag is set to YES all private members of a class 
# will be included in the documentation.  

EXTRACT_PRIVATE        = NO

# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will 
# evaluate all C-preprocessor directives found in the sources and include 
# files.

ENABLE_PREPROCESSING   = YES

# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro 
# names in the source code. If set to NO (the default) only conditional 
# compilation will be performed. Macro expansion can be done in a controlled 
# way by setting EXPAND_ONLY_PREDEF to YES.

MACRO_EXPANSION        = YES

# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES 
# then the macro expansion is limited to the macros specified with the 
# PREDEFINED and EXPAND_AS_DEFINED tags.

EXPAND_ONLY_PREDEF     = YES

【讨论】：

相关：显然，除非您设置 EXTRACT_STATIC = YES，否则 Doxygen 不会为 public static 类生成页面。显然 doxygen 认为 static 在 C# 中的含义与它在 C（即文件私有）中的含义相同，因为即使在 doxygen 的母语 C++ 中，static 通常也不是这个意思。出于某种原因，如果没有此选项，此类课程仍将在课程列表中列出（带有摘要），但从 v1.8.7 开始没有链接（不生成课程页面）。（PS 哇，这些虫子至少有 4 年的历史了？！）

【解决方案2】：

这是一个旧条目，但我遇到了同样的问题。

对我有用的一种方法是简单地使用 doxygen 的“预定义”功能。如果您预定义“internal=private”（相当于执行“#define internal private”），则 Doxygen 会将所有“内部”属性视为“私有”——因此如果需要，请忽略它们。

这是一个杂牌——但它确实有效。

【讨论】：

【解决方案3】：

doxygen 有几种方法可以通过在配置文件中设置选项来从文档中排除代码。

如果你的方法是私有的，那么设置EXTRACT_PRIVATE = NO

您还可以指定排除模式，例如，如果您的私有类位于名为 hidden 的目录中，您可以通过设置排除该目录中的所有文件。

EXCLUDE_PATTERNS = */hidden/*

您还可以通过设置避免包含未记录的代码。

HIDE_UNDOC_CLASSES = YES

和

HIDE_UNDOC_MEMBERS = NO

【讨论】：

这些是不同于私有类的 C# 内部类。它们具有程序集范围：只有同一程序集中的其他代码才能看到它们。我不希望这些类在文档中可见，我只希望公共类可见。

【解决方案4】：

刚刚碰到这个话题...使用 \internal doxygen 关键字，它就是为此而设计的。

【讨论】：

【解决方案5】：

设置

HIDE_UNDOC_CLASSES = YES

对我有用，即使在默认值上使用 EXTRACT_PRIVATE 和 PREDEFINED。不确定原因。我希望它们需要设置为NO（因此没有可用于私有成员的文档）和internal=private（因此也从内部类中删除了文档），但事实并非如此。 internal 和 private 类在生成的文档中不再提及。

【讨论】：

【解决方案6】：

Doxygen 显然认为 C# 类和结构的默认值是公共的，而不是内部的，并且会这样记录它们。但是，如果您明确使用 C# internal 访问修饰符，Doxygen 会尊重它（在一定程度上）。所以，在这个源上运行 Doxygen：

namespace Test_Library
{
    /// <summary>
    /// I should be documented.
    /// </summary>
    public class ExplicitPublicClass
    {
        public int Field;
    }

    /// <summary>
    /// I should NOT be documented.
    /// </summary>
    class ImplicitInternalClass
    {
        public int Field;
    }

    /// <summary>
    /// I should NOT be documented.
    /// </summary>
    internal class ExplicitInternalClass
    {
        public int Field;
    }

    /// <summary>
    /// I should be documented.
    /// </summary>
    public struct ExplicitPublicStruct
    {
        public int Field;
    }

    /// <summary>
    /// I should NOT be documented.
    /// </summary>
    struct ImplicitInternalStruct
    {
        public int Field;
    }

    /// <summary>
    /// I should NOT be documented.
    /// </summary>
    internal struct ExplicitInternalStruct
    {
        public int Field;
    }
}

在 Doxygen 的输出中为您获取这个类列表：

C ExplicitPublicClass       I should be documented.
C ExplicitPublicStruct      I should be documented.
C ImplicitInternalClass     I should NOT be documented.
C ImplicitInternalStruct    I should NOT be documented.

但是，您仍然可以在 Doxygen 的“命名空间参考”下的类列表中获得明确的内部类和结构：

class       ExplicitInternalClass
            I should NOT be documented. 

struct      ExplicitInternalStruct
            I should NOT be documented. 

class       ExplicitPublicClass
            I should be documented. More...

struct      ExplicitPublicStruct
            I should be documented. More...

class       ImplicitInternalClass
            I should NOT be documented. More...

struct      ImplicitInternalStruct
            I should NOT be documented. More...

但请注意，指向实际文档的“更多...”链接（以及相关类/结构名称中可用的链接）不适用于前两个。

因此，您可以通过使用 C# 的显式 internal 访问修饰符获得一些您正在寻找的行为，但不一定所有您正在寻找的行为为了。（相比之下，VSDocMan 完全按照您希望的方式处理上述源代码：仅记录了显式公共类和结构，没有提及显式或隐式内部类或结构。）

【讨论】：