Why does C# compiler includes non-public members in the XML documentation?

Question

When you compile your source code using csc.exe, you can use /doc option to save your xml documentation comments that are in the source file to an external xml file.

What I want to know is why the compiler includes the xml comments of the non-public members of my code in that file. Since I already have the documentation in the source code, I don't need anything that's in the xml documentation file while working on that project.

And if I use the dll for another project, I can't use the non-public members anyway. So why does it contain documentation for all the private and internal members?

I would also like to know if there is a way to prevent that.

Answer 1

I can understand internal members being documented - that way it may be easier to browse the documentation for code you're writing within the same assembly. (And there's always InternalsVisibleTo, of course.) For private members, I think it's a bit harder to justify.

If you use Sandcastle to generate offline documentation, you can ask it to generate a new XML file with only the public members - and only the summary parts, at that. I can't remember offhand what it looks like in SHFB, but in our Noda Time project file, I believe this is the relevant section:

  <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

Here's my VBScript to filter the xml documentation.

Change strInputFile, strOutputFile to your input and output XML documentation files. Also, change "arrWhiteList = Array ... " line, listing all types you'd like to have documentation for.

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