Ceci me sert de bloc-notes (d’aide mémoire), que je fait partager, les commentaires, critiques, … sont acceptés avec toutes les conséquences envisageables. .

// gr-1.cs created with MonoDevelop
// User: fulcanelli at 18:53 25/12/2007
//
// created on 25/12/2007 at 18:53

using System;
//Permets l'utilisation de types dans un espace de noms,
//de façon à ne pas avoir à qualifier l'utilisation d'un
//type dans cet espace de noms

/// <summary> La classe Hello affiche un message
/// de bienvenue à l'écran
/// </summary>

public class Hello
/*Le nom de la classe est suivi d'une accolade ouvrante
({). Tous les éléments compris entre cette accolade ouvrante
et l'accolade fermée (}) font partie de la classe.*/

/// <remarks> On utilisons l'E/S de la console.
/// Pour plus d'informations sur WriteLine, consultez
/// <seealso cref="System.Console.WriteLine"/>
/// </remarks>

{
      public static void Main()//Point de départ de l'application
      {
            Console.WriteLine("Hello, World!");
           //Ecrit sur la console. Si l'on n'avait pas utilisé
           // using System; on aurait écrit
           // System.Console.WriteLine("Hello, World!");
      }
}

Pour comprendre ce code lire les commentaires.

Sur les commentaires, trois choses :

//Permets l'utilisation de types dans un espace de noms,
//de façon à ne pas avoir à qualifier l'utilisation d'un
//type dans cet espace de noms

Est un commentaire interne au programme. Ligne par ligne.

/*Le nom de la classe est suivi d'une accolade ouvrante
({). Tous les éléments compris entre cette accolade ouvrante
et l'accolade fermée (}) font partie de la classe.*/

Est un commentaire interne au programme. Au format bloc sur plusieurs lignes.

/// <remarks> On utilisons l'E/S de la console.
/// Pour plus d'informations sur WriteLine, consultez
/// <seealso cref="System.Console.WriteLine"/>
/// </remarks>

Est un commentaire de documentation qui va permettre de générer un fichier XML à la compilation.

fulcanelli@fulcanelli:$ mcs gr-1.cs
fulcanelli@fulcanelli:$ ls
bin  gr-1.cs  gr-1.exe  teste-gtk.cs  teste-gtk.exe

Compilation normal.

fulcanelli@fulcanelli:$  mcs -doc:comment-gr-1.xml gr-1.cs
gr-1.cs(16,14): warning CS1587:
XML comment is not placed on a valid language element
Compilation succeeded - 1 warning(s)
fulcanelli@fulcanelli:~/Projects/teste-gtk$

Compilation avec génération de la documentation XML. A noter que la balise <remarks> </remarks> n’est pas reconnue et génère un warning.
Le fichier XML obtenu :

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>gr-1</name>
    </assembly>
    <members>
        <member name="T:Hello">
            <summary> La classe Hello affiche un message
            de bienvenue à l'écran
            </summary>
        </member>
    </members>
</doc>

Sortie sur la console :

fulcanelli@fulcanelli:$ ./gr-1.exe
Hello, World!
fulcanelli@fulcanelli:$

Quelques balises XML :

<summary>...</summary>

Fournir une brève description. Utilisez la balise <remarks> pour une description plus longue.

<remarks> ... </remarks>

Fournir une description détaillée. Cette balise peut contenir des paragraphes imbriqués, des listes et d’autres types de balises.

<para> ... </para>

Cette balise est à utiliser à l’intérieur d’une autre balise, telle que <summary>, <remarks> ou <returns> et vous permet de structurer le texte.

<list type="type_de_liste"> ... </list>

Ajouter une liste structurée ou un tableau à une description détaillée. type_de_liste peut valoir «bullet» (à puce), «number» (numérotée) ou table (tableau). des balises supplémentaires(<term> ... </term> et <description> ... </description>) peuvent être utilisées pour mieux définir la structure.

<example> ... </example>

Fournir un exemple d’utilisation d’une méthode, d’une propriété ou d’un autre membre de la bibliothèque. Cela implique souvent l’utilisation d’une balise <code> ... imbriquée.

<code> ...

Indique que le texte est un code d’application.

<c> ... </c>

Indique que le texte est un code d’application. La balise <code> est utilisée pour les lignes de code qui doivent êytre séparées de toutes description jointe. La balise <c> est utilisée pour le code incorporée à une description jointe

<see cref="member"/>

Indique la référence à un autre membre ou champ. Le compilateur vérifie que ce «membre» existe réellement.

<seealso cref="member"/>

Indique la référence à un autre membre ou champ. le compilateur vérifie que ce «membre» existe réellement. La différence entre les balises <see> et <seealso> dépend du processeur qui manipule le docuement XML. Le processeur doit pouvopir générer les sections See (voir) et See Also (voir aussi) pour que ces deux balises soient correctement différenciées.

<exception> ... </exception>

Fournit une description pour une classe d’exception.

<permission> ... </permission>

Documenter l’accessibilité d’un memmbre

<param name="name"> ... </param>

Fournit une description pour un paramètre de méthode.

<returns> ... </returns>

Documenter la valeur renvoyée et le type de méthode.

<value> ... </value>

Décrit une propriété.

Documentation Microsoft sur les balises de documentation XML.

Voilà pour le moment.

Si j’ai dis une (des) connerie(s), un manque, une question, un éclaircissement, hop un petit commentaire

Ce billet a été posté le Mercredi 26 décembre 2007 à 13:33 dans C#, GNU/Linux, Programmation. Vous pouvez suivre les réponses à ce billet avec le flux RSS 2.0. Vous pouvez laisser une réponse, ou faire un trackback sur votre site.