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>