Exporter (0) Imprimer
Développer tout

Génération de documentation pour des applications Visual Basic .NET

Visual Studio .NET 2003

Résumé : Cet article explique comment utiliser un outil PowerToy gratuit pour ajouter de la documentation XML de support à votre application Visual Basic .NET et créer de la documentation lorsque vous rédigez du code. Cet article contient des liens vers des pages en anglais. (17 pages imprimées).

Lire l'article en anglais 

Sur cette page

Introduction Introduction
Documentation inline avec VBCommenter Documentation inline avec VBCommenter
Conclusion Conclusion

Introduction

Dans un projet type, la tâche consistant à documenter le code est souvent reléguée en fin de cycle. Bien que l'importance de la documentation ait été très souvent soulignée, les développeurs consacrent généralement la majeure partie du projet à créer de nouvelles fonctionnalités et finissent par ne pas finaliser ce qu'ils redoutent : la rédaction de la documentation. De même qu'en matière d'entretien ménager, on s'accorde à dire qu'il faut nettoyer au fur et à mesure, la meilleure façon de produire une documentation de grande qualité pour votre projet est de le documenter au fur et à mesure.

Dans Visual Studio .NET 2003, la documentation sur le code XML est prise en charge en C# mais pas en Visual Basic .NET. Vous pouvez néanmoins télécharger un plug-in gratuit appelé VBCommenter PowerToy pour activer la documentation XML inline dans Visual Studio .NET 2003. Pour télécharger VBCommenter, accédez à l'adresse suivante :

http://www.gotdotnet.com/workspaces/workspace.aspx?id=112b5449-f702-46e2-87fa-86bdf39a17dd.

Documentation inline avec VBCommenter



Pour voir comment fonctionne VBCommenter, créons un nouveau projet de bibliothèque de classes dans Visual Studio .NET 2003, comme illustré à la figure 1. Je vais créer une définition de classe, puis lui ajouter une documentation XML.

vbgeneratingdoc_fig01.gif

Figure 1. Création d'un projet de bibliothèque de classes

Pour cet exemple, j'ai défini une simple classe Point. Après avoir installé VBCommenter, vous pouvez insérer un commentaire XML en tapant trois apostrophes (') avant une définition de classe, une propriété, des variables de membre ou une méthode (voir figure 2).

vbgeneratingdoc_fig02.gif

Figure 2. Ajout de commentaires XML au code

Lorsque vous appuyez sur Entrée, le modèle de document XML représenté en figure 3 est automatiquement généré.

vbgeneratingdoc_fig03.gif

Figure 3. Modèle de commentaire XMl généré

Vous pouvez configurer les paramètres de VBCommenter en accédant à Outils-> VBCommenter Options (voir figure 4).

vbgeneratingdoc_fig04.gif

Figure 4. Configuration de VBCommenter

La liste 1 à la fin de cet article montre la documentation XML complète pour cette classe Point. Je vais souligner ici quelques points importants.

Vous pouvez obtenir la liste des balises de documentation XML sur le site MSDN à l'adresse suivante : http://msdn.microsoft.com/library/default.asp?url=/library/en-us/csref/html/vclrfTagsForDocumentationComments.asp.Voici la liste :

  • <c>

  • <para>

  • <see>

  • <code>

  • <param>

  • <seealso>

  • <example>

  • <paramref>

  • <summary>

  • <exception>

  • <permission>

  • <value>

  • <include>

  • <remarks>

  • <list>

  • <returns>

À titre d'exemple, examinons la documentation que j'ai générée pour l'une des méthodes surchargées :

	''' <overloads>
	
	''' Calculates the distance between two points
	
	''' </overloads>
	
	''' 
	
	''' <summary>
	
	''' Calculates the distance of a point from the origin
	
	''' </summary>
	
	''' 
	
	''' <returns>The distance between the current point and the origin
	
	''' </returns>
	
	''' <example> This sample shows how to call the <c>length()</c> 
	
	''' method
	
	''' <code>
	
	'''    Dim ptA As New Point(3, 4)
	
	'''    Dim distance As Single = ptA.length()
	
	''' </code>
	
	''' </example>
	
	''' 
	
	''' <remarks>
	
	''' </remarks>
	
	''' <history>
	
	'''    [Wei-Meng Lee]   9/27/2004   Created
	
	''' </history>
      

Vous remarquerez qu'il y a un nouvel élément, <overloads>, qui n'apparaît pas dans la liste de la documentation MSDN. L'élément <overloads> est utilisé pour donner une description générale des méthodes surchargées. Vous verrez plus tard le rôle de cet élément, lorsque nous générerons la documentation avec l'outil NDOC. Notez que vous n'avez besoin de spécifier l'élément <overloads> que pour l'une des méthodes surchargées (celle de votre choix).

Vous pouvez aussi inclure des exemples de code dans votre documentation au moyen de la balise <example>. Pour mettre en forme un mot (ou une phrase) en tant que code, utilisez la balise <c>. Si le code contient plusieurs lignes, utilisez la balise <code>.

Comme les commentaires XML que vous ajoutez à votre code risquent de le rendre difficilement lisible, vous pouvez les masquer en cliquant sur le signe moins (« - ») à gauche de la fenêtre de code. Pour faire apparaître ces commentaires, cliquez sur le signe plus (« + »), comme indiqué à la figure 5.

vbgeneratingdoc_fig05.gif

Figure 5. Masquage des commentaires

Après avoir commenté votre code, recréez vos classes. Vous pourrez ainsi trouver un document XML portant le même nom que votre projet dans le dossier bin de celui-ci. La figure 6 illustre la structure du document XML.

vbgeneratingdoc_fig06S.gif

Figure 6. Document XML généré par VBCommenter

Génération de la documentation

Avec la documentation XML générée par VBCommenter, vous avez désormais deux options en matière de documentation :

  1. Écrire vos propres feuilles de style de transformation XSLT pour transformer le document XML en format lisible comme HTML, PDF, etc.

  2. Utiliser un outil tiers pour analyser automatiquement la documentation XML dans les différents formats de documentation pris en charge.

J'ai choisi la seconde option et j'utilise NDoc (http://ndoc.sourceforge.net/), générateur de documentation de code pour .NET. NDoc est un outil libre et gratuit qui génère de la documentation dans plusieurs formats : aide HTML de type MSDN (.chm), aide Visual Studio .NET (HTML Help 2) et pages Web de type MSDN-Online.

La version actuelle de NDoc est la version 1.3 (bêta). Vous pouvez installer NDoc pour différentes versions de .NET (Mono, .NET 1.0 ou .NET 1.1). J'ai choisi .NET 1.1, puisque j'utilise Microsoft Visual Studio .NET 2003.

Une fois NDoc installé, vous verrez apparaître la fenêtre illustrée à la figure 7 au lancement de l'application. Vous pouvez choisir le type de documentation que vous souhaitez générer en le sélectionnant dans la zone de liste déroulante.

vbgeneratingdoc_fig07.gif

Figure 7. Lancement de NDoc

Cliquez sur Add pour ajouter le nom de fichier de l'assembly (voir figure 8). Une fois l'assembly sélectionné (dans mon exemple, MyPoint.dll dans le dossier bin), le champ du nom de fichier du document XML est automatiquement renseigné (même nom que l'assembly mais avec une extension .XML).

vbgeneratingdoc_fig08.gif

Figure 8. Ajout d'un assembly à NDoc

Vous pouvez ajouter plusieurs projets dans la même documentation en ajoutant chaque assembly dans le projet NDoc.

Dès que vous êtes prêt à créer la documentation, cliquez sur le bouton Build Documentation de la barre d'outils, comme illustré à la figure 9.

vbgeneratingdoc_fig09.gif

Figure 9. Création de la documentation

Pour afficher la documentation, cliquez sur le bouton View Documentation de la barre d'outils (figure 10).

vbgeneratingdoc_fig10.gif

Figure 10. Affichage de la documentation

La documentation générée s'affiche comme illustré à la figure 11. (J'ai affiché l'arborescence dans le panneau de gauche pour montrer la documentation complète.)

vbgeneratingdoc_fig11.gif

Figure 11. Documentation de style MSDN générée

Nous allons nous intéresser à la documentation générée par les balises présentées précédemment. En particulier, examinons la documentation de la méthode surchargée length() illustrée à la figure 12.

vbgeneratingdoc_fig12.gif

Figure 12. Relation entre le balisage XML et de la documentation générée

Comme vous le voyez, le texte dans l'élément <overloads> sert à fournir une description générale de la méthode surchargée, tandis que la description réelle de chaque méthode surchargée est décrite par l'élément <summary>. Si vous n'utilisez la balise <overloads> pour aucune des méthodes surchargées, NDoc emploiera comme description générale des méthodes surchargées le texte trouvé dans le premier élément <summary>.

Cliquez sur la première méthode surchargée de la méthode length() pour voir la relation entre le balisage de documentation et la documentation obtenue (figure 13).

vbgeneratingdoc_fig13.gif

Figure 13. Relation entre le balisage XML et la documentation générée

Notez que l'élément <remarks> étant vide, la section Remarks de la documentation le sera également. Si vous n'utilisez pas l'élément <remarks>, la section Remarks ne sera pas générée.

Distribution de la documentation

Si vous accédez à la section des propriétés dans NDoc, vous pouvez spécifier l'emplacement de la documentation générée en changeant l'attribut OutputDirectory. Dans la figure 14, ma documentation sera enregistrée dans le dossier c:\documentation.

vbgeneratingdoc_fig14.gif

Figure 14. Configuration du répertoire de sortie de la documentation

Une fois la documentation créée, vous pouvez voir la liste des fichiers générés à la figure 15.

vbgeneratingdoc_fig15.gif

Figure 15. Affichage de la documentation générée

Si vous souhaitez distribuer la documentation pour votre classe, il vous suffit de distribuer le fichier portant l'extension .chm. Il s'agit de l'aide HTML compilée. Ce fichier n'a pas besoin des autres fichiers HTML générés dans le même dossier.

Conclusion

Dans cet article, vous avez vu comment ajouter des commentaires XML dans des applications Visual Basic .NET et utiliser un outil tiers pour générer la documentation pour une application. Tous les outils présentés dans cet article sont gratuits et constituent donc une méthode très pratique pour entreprendre la documentation de vos applications. Si vous connaissez d'autres outils intéressants permettant de générer de la documentation pour du code, n'hésitez pas à m'en faire part à l'adresse suivante : wei_meng_lee@hotmail.com.


Component tag found.

Wei-Meng Lee (Microsoft .NET MVP, Singapour) est technologue et fondateur de Developer Learning Solutions, société spécialisée dans les formations pratiques sur les dernières technologies Microsoft. Wei-Meng intervient régulièrement dans des conférences internationales et a participé en tant qu'auteur ou collaborateur à de nombreux ouvrages sur .NET, XML et les technologies sans fil, notamment Windows XP Unwired et .NET Compact Framework Pocket Guide, deux ouvrages publiés par O'Reilly Media, Inc. Il écrit très souvent sur le réseau O'Reilly, abordant des thèmes qui vont de .NET à Mac OS X

Liste 1

''' -----------------------------------------------------------------------------
''' Project    : MyPoint
''' Class    : Point
''' 
''' -----------------------------------------------------------------------------
''' <summary>
''' The Point class contains 2 properties, 1 overloaded constructor, and 
''' 1 overloaded method
''' </summary>
''' <remarks>
''' If you need to use the Point class in the System.Drawing namespace, be 
''' sure to reference it using the fullname, i.e. System.Drawing.Point
''' </remarks>
''' <history>
'''    [Wei-Meng Lee]   9/26/2004   Created
''' </history>
''' 
''' -----------------------------------------------------------------------------
Public Class Point
	Private ptX, ptY As Integer
	Private Shared count As Integer
	''' -----------------------------------------------------------------------------
	''' <summary>
	''' Empty constructor
	''' </summary>
	''' <remarks>
	''' Creates a new instance of the Point class
	''' </remarks>
	''' <history>
	'''    [Wei-Meng Lee]   9/26/2004   Created
	''' </history>
	''' -----------------------------------------------------------------------------
	Public Sub New()
		count += 1
	End Sub

	''' -----------------------------------------------------------------------------
	''' <overloads>
	''' Constructor
	''' </overloads>
	''' <summary>
	''' Constructor with two parameters
	''' </summary>
	''' <param name="x"></param>
	''' <param name="y"></param>
	''' <remarks>
	''' Creates a new instance of the Point class
	''' <para>
	''' Parameter x is assigned to the x-coordinate and 
	''' Parameter y is assigned to the y-coordinate 
	''' </para>
	''' </remarks>
	''' <history>
	'''    [Wei-Meng Lee]   9/26/2004   Created
	''' </history>
	''' -----------------------------------------------------------------------------
	Public Sub New(ByVal x As Integer, ByVal y As Integer)
		ptX = x
		ptY = y
		count += 1
	End Sub

	''' -----------------------------------------------------------------------------
	''' <summary>
	''' Property for x-coordinate
	''' </summary>
	''' <returns>The x-coordinate</returns>
	''' <history>
	'''    [Wei-Meng Lee]   9/26/2004   Created
	''' </history>
	''' -----------------------------------------------------------------------------
	Property x() As Integer '   sets the X coordinate
		Get
		Return ptX
		End Get
		Set(ByVal Value As Integer)
			If Value < 500 And Value > -500 Then
				ptX = Value
			End If
		End Set
	End Property

	''' -----------------------------------------------------------------------------
	''' <summary>
	''' Property for y-coordinate
	''' </summary>
	''' <returns>The y-coordinate</returns>
	''' <history>
	'''    [Wei-Meng Lee]   9/26/2004   Created
	''' </history>
	''' -----------------------------------------------------------------------------
	Property y() As Integer '   sets the Y coordinate
		Get
			Return ptY
		End Get
		Set(ByVal Value As Integer)
			ptY = Value
		End Set
	End Property
	''' -----------------------------------------------------------------------------
	''' <overloads>
	''' Calculates the distance between two points
	''' </overloads>
	''' 
	''' <summary>
	''' Calculates the distance of a point from the origin
	''' </summary>
	''' 
	''' <returns>The distance between the current point and the origin
	''' </returns>
	''' <example> This sample shows how to call the <c>length()</c> 
	''' method
	''' <code>
	'''    Dim ptA As New Point(3, 4)
	'''    Dim distance As Single = ptA.length()
	''' </code>
	''' </example>
	''' 
	''' <remarks>
	''' </remarks>
	''' <history>
	'''    [Wei-Meng Lee]   9/27/2004   Created
	''' </history>
	''' -----------------------------------------------------------------------------
	Public Function length() As Single
		Return Math.Sqrt(Math.Pow(ptX, 2) + _
			Math.Pow(ptY, 2))
	End Function
	''' -----------------------------------------------------------------------------
	''' <summary>
	''' Calculates the distance of a point from another point
	''' </summary>
	''' 
	''' <param name="pointOne">A Point object</param>
	''' <returns>The distance between the current point and the 
	''' specified point
	''' </returns>
	''' 
	''' <example> This sample shows how to call the <c>length()</c> method 
	''' with a point specified
	''' <code>
	'''    Dim ptA As New Point(3, 4)
	'''    Dim ptB As New Point(7, 8)
	'''    Dim distance As Single = ptA.length(ptB)
	''' </code>
	''' </example>
	''' <remarks>
	''' 
	''' </remarks>
	''' 
	''' <history>
	'''    [Wei-Meng Lee]   9/27/2004   Created
	''' </history>
	''' -----------------------------------------------------------------------------
	Public Function length(ByVal pointOne As Point) As Single
		Return Math.Sqrt(Math.Pow(ptX - pointOne.x, 2) + _
			Math.Pow(ptY - pointOne.y, 2))
	End Function
End Class
			
Afficher:
© 2014 Microsoft