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

Question

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

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

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

我还想知道是否有一种方法可以防止这种情况发生。

- Şafak Gür

---

我认为将所有内容放入XML文件中存在缺点。在我看来，从你的XML文件创建可读文档的工具过滤适当的内容是其责任。 - CodesInChaos

@CodesInChaos：你说得对。虽然我仍认为应该有一个选项仅为公共成员生成文档。(我在编写API dll，并且不希望提供的XML文档文件包含有关我的库内部信息的内容。我希望不需要eazfuscator的文档过滤器，但似乎我确实需要。) - Şafak Gür

提取仅限公共成员的XML注释。相关链接：https://dev59.com/tXRB5IYBdhLWcg3wbGxB - CodesInChaos

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>

- Jon Skeet

Answer 2

这是我用VBScript编写的筛选xml文档的代码。

请将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()

- Soonts