1 / 12

Program documentaiton

Program documentaiton. Using the Doxygen tool. C# comment styles. The C# compiler recognizes a number of comment styles, including // the rest of the line is a comment /* this is a comment */ /// the rest of the line is a comment, XML style

shelley
Télécharger la présentation

Program documentaiton

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  1. Program documentaiton Using the Doxygen tool

  2. C# comment styles • The C# compiler recognizes a number of comment styles, including • // the rest of the line is a comment • /* this is a comment */ • /// the rest of the line is a comment, XML style • The 3-slash comment style is the most interesting.

  3. What to document • All public and protected parts of a program should be documented using /// comments • Private parts are not that important to document since they are only for internal use • Classes • Write a /// comment in front of the class declaration. • Mention class invariants, if any. • Thread safety • Methods • Write a /// comment in from of the method declaration. • Document parameters, returned values, and exceptions thrown

  4. Documenting methods • Document the contract between the method and its callers • Focus on what the method does, not how • The how might change in the future, while the what should remain constant over time • Preconditions • Postconditions • Side effects • Thread safety

  5. Tags for documentation comments • The 3-slash comments can include some special tags, like • <summary>description of class or method</summary> • <param name=“theParametersname”>description</param> • <returns>description</returns> • <exceptioncref=“exceptionClass”>description</exception> • <value>property description</value> • Properties should have summary + value • <c>text</c>, code, single word • <code>text</code> code, multiple lines • http://msdn.microsoft.com/en-us/library/5ast78ax.aspx

  6. Assistance from Visual Studio • Visual Studio can help you write 3-slash comments for methods. • In front of the method write the 3 slashes and press ‘return’ • Visual Studio will now generate a comment template to document parameters, return values, etc. • This is a template! You have to fill out the template!!

  7. Doxygen • Doxygen is a tool to extract comments, declarations, etc. from C# files and generate HTML pages. • Doxygen can be used with other languages than C#. • Doxygen can has other output formats than HTML • Doxygen can be run from the from the command line • Doxygen comes in a free and a paid edition • http://www.stack.nl/~dimitri/doxygen/index.html

  8. Doxygen XML commands • Doxygenrecognices the standard tags for documentation comments and adds at least one extra commands • <inheritdoc> insert the documentation from the base class method • http://www.stack.nl/~dimitri/doxygen/manual/xmlcmds.html

  9. Doxygen configuration scripts • To run Doxygen on more than the very simple cases you must make a configuration file • Syntax is MAKE like • ComandLine:>doxygenconfFile • Doxygen comes with a wizard that can help make a configuration file • Doxywizard • Go through the wizard, press “save” and you have a configuration file

  10. Other special comments: TODO and HACK • Visual Studio recognizes a few other special comments, like • // TODO some comment • // HACK some comment • Note: 2 slashes, not 3 slashes • Theses special comments can be viewed in Visual Studio • Menu View -> Task List • Use for internal developer comments • Reference • http://msdn.microsoft.com/en-us/library/vstudio/zce12xx2(v=vs.100).aspx

  11. Technical writers vs. programmers • Programmers are supposed to writhe the program code and the comments • Programmers are usually better writing code than comments. • Some companies employ technical writers who write program documentation • Comments in the source code • Reference documentation • User manuals • Tutorials • etc.

  12. References and further reading • MSDN Recommended Tags for Documentation Comments • http://msdn.microsoft.com/en-us/library/5ast78ax.aspx • Doxygen • http://www.stack.nl/~dimitri/doxygen/index.html

More Related