is XML Documentation used to document the external API only?

Question

I am using XML Documentation comments to document a new project. All of my public API methods are documented using the three slashes required for XML documentation.

My internal methods (protected and private) are documented using double slashes (//) and slash star (/* */). This is because I do not believe these comments should appear in the public API documentation. For example, I developed a group of classes today that use the Chain of Responsibility pattern (http://www.dofactory.com/net/chain-of-responsibility-design-pattern), however I do not believe the users of these classes need to know that the Chain of Responsibility pattern is used internally - only others developers of these classes need to know this.

Have I understood this correctly i.e. is XML Documentation used to document the external API only? Should I even be saying that these classes use the Chain of Responsibility pattern (or whatever pattern I use).

The reason I ask is because other developers will be looking at this code soon and I am trying to promote the principle of least astonishment.

Answer 1

I do not believe these comments should appear in the public API documentation

For private, that is correct. For protected methods of non-sealed classes, the public API documentation should definitely contain a description, since they can be called in a derived class, by some user of your library.

Have I understood this correctly i.e. is XML Documentation used to document the external API only.

That, however, is IMHO not a good idea. If you don't want the XML documentation of private methods to appear in the public API docs, better find a way to configure your documentation generation tool not to put those private Xml comments into the generated document. If you are using Sandcastle for generating your docs, this seems to be the default.

XML comments for all methods, including private methods, is useful for yourself or your team (the maintainer of the library), because it is displayed by Visual Studio's intellisense feature when you use such a method. Moreover, it will become pretty cumbersome and error-prone to use a different comment syntax for private methods than for everything else, or to change the comment syntax whenever you make a public method private or vice versa.

Answer 2

That depends, is this documentation going to be provided to external customers or is it for internal reference? If you’re providing it to external devs, then only public & protected comments should be generated in the docs. If you’re using it for internal purposes, feel free to generate docs for anything that has a doc comment. I had a project where we wanted both, so I set up two different SandCastle projects, one for the customer and one that was published to our internal intranet.

Either way, it’s not a question of what should have a comment, it’s a question of what comments are included in your document generation.

By default, SandCastle does not export doc comments for private methods, so you can go ahead and add doc comments for private methods if you want to. They won’t be exported to the generated docs unless you explicitly tell SandCastle to do so.