为什么 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()