3

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.

  • Sounds reasonable to me. – Robert Harvey Jan 5 '18 at 16:16
  • Is it reasonable to state what pattern is used in the internal documentation or should this be stated somewhere else? I realise this further question may sound a little pedantic, however I am asked to follow this principle of least astonishment. – w0051977 Jan 5 '18 at 16:19
  • I don't find anything in your post astonishing. – Robert Harvey Jan 5 '18 at 17:22
  • If other developers are working on the source code, the pattern of comments for private members will be self-evident. I don't think you need to "announce" it anywhere. – Mark Benningfield Jan 6 '18 at 1:24
  • @RobertHarvey: it does not sound reasonable to me to apply such ugly workarounds for hiding documentation of private methods to the outside world. I am pretty sure that is not necessary. – Doc Brown Jan 6 '18 at 11:06
5

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.

  • Is it reasonable to state what pattern is used in the internal documentation or should this be stated somewhere else? +1 for the first paragraph. – w0051977 Jan 5 '18 at 23:01
  • @w0051977: well, since you said "for the first paragraph", it seems you had problems to follow the arguments of the second one? And when you follow my advice, there is "no special pattern" to be stated. – Doc Brown Jan 6 '18 at 6:13
1

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.

  • +1 for suggesting two Sandcastle projects (one for API users and one for customer). Does Sandcastle even publish comments on private members? – w0051977 Jan 6 '18 at 12:34
  • It’s not the default behavior, but you can enable it if you want. ewsoftware.github.io/SHFB/html/… – RubberDuck Jan 6 '18 at 12:40
  • So it is disabled by default? - that is what I want (then I can document my private members without exposing the documentation to the API). – w0051977 Jan 6 '18 at 12:50
  • Yup. Disabled by default. You can document to your heart’s content and private methods won’t show up in the docs unless you want them to. – RubberDuck Jan 6 '18 at 12:59
  • Finally, is it "normal" to specify the design patterns used in the "private" documentation? For example: "Chain of Responsibility is used here to ........". As discussed I am trying to promote the principle of least astonishment. – w0051977 Jan 6 '18 at 13:00

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.