c# - 为什么 C# 编译器在 XML 文档中包含非公共成员？

Question

使用 编译源代码csc.exe时，可以使用/doc选项将源文件中的 xml 文档注释保存到外部 xml 文件中。

我想知道的是为什么编译器在该文件中包含我的代码的非公共成员的 xml 注释。由于我已经拥有源代码中的文档，因此在处理该项目时我不需要 xml 文档文件中的任何内容。

如果我将 dll 用于另一个项目，我无论如何都不能使用非公共成员。那么为什么它包含所有私人和内部成员的文档呢？

我也想知道是否有办法防止这种情况。

Answer 1

我可以理解正在记录的内部成员 - 这样可以更轻松地浏览文档以查找您在同一程序集中编写的代码。（当然，总是有 InternalsVisibleTo。）对于私人会员，我认为它有点难以证明。

如果您使用 Sandcastle 生成离线文档，您可以要求它生成一个新的 XML 文件，其中只有公共成员 - 并且只有摘要部分。我不记得它在 SHFB 中的样子，但在我们的 Noda Time 项目文件中，我相信这是相关部分：

  <ComponentConfig id="IntelliSense Component" enabled="True">
    <component id="IntelliSense Component" 
               type="SandcastleBuilder.Components.IntelliSenseComponent" 
               assembly="{@SHFBFolder}SandcastleBuilder.Components.dll">
      <output includeNamespaces="false" namespacesFile="Namespaces" 
              folder="{@OutputFolder}\..\PublicApi" />
    </component>
  </ComponentConfig>

Answer 2

这是我过滤 xml 文档的 VBScript。

将 strInputFile、strOutputFile 更改为您的输入和输出 XML 文档文件。此外，更改“arrWhiteList = Array ...”行，列出您想要为其提供文档的所有类型。

option explicit

const strInputFile = "C:\Temp\YourModule.XML"
const strOutputFile = "C:\Temp\YourModule.filtered.XML"

Dim arrWhiteList
arrWhiteList = Array( "MyNamespace.Type1", "MyNamespace.Type2", "MyNamespace.Type3" )

Function isNameOk( strName )
    Dim className, i

    for each className in arrWhiteList
        i = InStr(strName, className)
        if i = 3 Then
            isNameOk = True
            exit function
        end if
    Next
    isNameOk = false
end function

Sub Main()
    Dim objXml, dicToRemove
    Set objXml = CreateObject("Msxml2.DOMDocument.6.0")
    objXml.Load strInputFile

    Set dicToRemove = CreateObject( "Scripting.Dictionary" )

    Dim node, strName
    for each node in objXml.documentElement.SelectNodes( "//member" )
        strName = node.getAttribute( "name" )
        if not isNameOk( strName ) then
            dicToRemove.add node, ""
        end if
    Next

    Dim nodeMembers, arrKeys
    Set nodeMembers = objXml.documentElement.SelectSingleNode( "//members" )
    arrKeys = dicToRemove.Keys

    for each node in arrKeys
        nodeMembers.removeChild node
    next

    objXml.save strOutputFile
End Sub

Call Main()