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.

I see now downsides to putting everything into the XML file. IMO it's the responsibility of the tool that creates readable documentation from your xml file to filter appropriately. — CodesInChaos, Feb 09 '13 at 10:03
@CodesInChaos: You have a point, yes. Although I still think that there should be an option for it to generate documentation for only the public members. (I'm working on an API dll and I don't want the XML documentation file that I'll provide contain information about the internals of my library. I hoped not to need eazfuscator's documentation filter for that, but seems like I do) — Şafak Gür, Feb 09 '13 at 10:10
Related [Extract xml comments for public members only](http://stackoverflow.com/questions/624466/extract-xml-comments-for-public-members-only) — CodesInChaos, Feb 09 '13 at 10:25

score 5 · Accepted Answer · answered Feb 09 '13 at 10:05

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>

score 1 · Answer 2 · answered Jul 20 '14 at 15:42

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

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

2 Answers2