Cursus c# : documentatie maken

Wanneer je de programmacode die je schrijft goed voorziet van commentaar, dan zal je code gemakkelijker te begrijpen zijn wanneer je er later naar terugkijkt of wanneer je die doorgeeft aan een andere programmeur.

Wanneer je commentaar op een specifieke manier aanbrengt, kan je met Visual Studio.net automatisch documentatierapporten laten genereren.

Code documenteren

Om code te documenteren kan je standaard gebruik maken van // voor commentaar op een regel en /* ... */ voor commentaar op meerdere regels.

Wens je echter met Visual Studio.net automatisch een 'Comment Report' aan te maken, dan plaats je commentaar naast /// en gebruik je vooraf gedefiniëerde XML-markeringen:

Markering	Betekenis
summary	Beschrijving van een member: klasse, variabele, methode, constructor, ...
c	Code in een regel
code	Codeblok van meerdere regels
returns	retourwaarde van een methode
param	parameter voor een methode
...	Meer info bij MSDN

Je kan ook HTML-tags gebruiken in commentaar, zodat het gegenereerde rapport wordt opgemaakt volgens jouw wensen.

Via het menu Tools > Build Comment Web Pages kan je een automatisch rapport laten genereren.

Meer over Code Comment Web Report bij MSDN

Voorbeeld

Als voorbeeld zie je hieronder de klasse Persoon met VS.net commentaarstijl:

using System;

namespace Personen
{
	/// <summary>
	/// Klasse voor een Persoon
	/// </summary>
	public class Persoon
	{
		/// <summary>
		/// Enumeratie voor het geslacht.<br></br> 
		/// Zo kan enkel Mannelijk of Vrouwelijk worden gekozen
		/// </summary>
		public enum Geslacht { Mannelijk, Vrouwelijk }
		
		/// <summary>
		/// Naam van de persoon
		/// </summary>
		protected string naam;
		/// <summary>
		/// Geslacht van de persoon
		/// </summary>
		protected Geslacht geslacht;

		
		/// <summary>
		/// Constructor
		/// </summary>
		/// <param name="naam">Naam van de Persoon</param>
		/// <param name="geslacht">Geslacht van de Persoon</param>
		public Persoon(string naam, Geslacht geslacht)
		{
			this.naam = naam;
			this.geslacht = geslacht;
		}
		
		/// <summary>
		/// Maak een beschrijvende zin
		/// </summary>
		/// <returns>string die de <b><c>Persoon</c></b> beschrijft</returns>
		public override string ToString()
		{
			return naam +" " +geslacht;
		}
	}
}

Je kan op deze manier een rapport maken van een volledige Solution of Project.

c# : documentatie maken

Inleiding

Code documenteren

Voorbeeld

Oefeningen