Adding Code Examples to Documentation Comments

[ERR!]
added by BlackWasp
6/1/2012 9:06:37 AM

299 Views

Documentation for code libraries is generally improved with the addition of sample code that shows how those libraries are used. When using XML documentation comments, three tags can be used to incorporate examples within the compiled help file.

Read the full story
C#
2 comments
dpeterson
6/1/2012 9:07:07 AM
Even in open source code I don't see people taking advantage of this approach to commenting enough. Perhaps it's because of the difficulty for newcomers in setting up something like Sandcastle? Maybe people just don't want to be bothered making the comments if they can't figure out the documentation generation.
BlackWasp
6/1/2012 11:59:21 AM
I think also that there is a push from some not to comment at all and that leads some developers to omit documentation. Of course, we all like coding more than documenting ;)

That said, with Sandcastle Help File Builder's guided installation it's a breeze to get going. You can see my article on this at http://www.blackwasp.co.uk/Sandcastle.aspx.