Discussion :

[saad.hessane]

Bonjour tout le monde.
Je voudrais savoir s'il y a possibilité avec Visual Studio 2010 de générer de la doc automatiquement. Du genre quand on crée un nouveau fichier source il insère automatiquement en haut le nom du développeur, le nom du fichier et une description. Même chose pour les fonctions avec une sorte de raccourci clavier.
Je le faisais avec Eclipse en Java, et je trouvais ça assez utile.
Ca serait bien aussi s'il pouvait générer la documentation correspondante à une solution.
Merci d'avance.

[bacelar]

Vous abordez dans votre question des choses bien différentes.

Les cartouches de commentaire en tête de fichier indiquant qui à fait quoi et quand, c'était bon il y a 30 ans. Maintenant il faut utiliser les outils de gestion de version logicielle comme CVS, Subversion, TFS, ClearCase qui vous donneront des informations bien plus exactes, précise, et sans aucune surcharge pour le développeur. Quel bonheur la commande "Blame" avec ce type d'outil.

Il reste les commentaires proches du code comme lors de la déclaration de classe ou de méthode. Eclipse n'est pas l'outil que vous utilisiez pour générer la documentation mais était l'interface d'accès à l'outil JAVADOC qui génère une documentation à partir de commentaire au format JAVADOC. Eclipse est là pour la gestion des raccourcis claviers et générer des commentaires au format JAVADOC en fonction de la signature des méthodes.

Je précise cela car sous VS, il y a le même découpage et le niveau de fonctionnalité en fonction du langage.

L'équivalent des commentaires JAVADOC sous VS, c'est les "XML Comment" et avec une syntaxe assez proche.
VS génère directement une documentation au format XML :http://msdn.microsoft.com/en-us/library/ms177226.aspx.

Le hic, c'est que cette documentation est exploitable par VS pour Intellisense (Et là, je suis un grand fan, bien plus qu'une documentation en HTML ou en PDF). Mais pour générer une documentation technique (qui ne sert qu'à faire de la lèche au CP car Intellisence est bien plus utile) il faut passer par des outils supplémentaire qui convertissent cette documentation xml en d'autre formats. L'exemple de programme le plus connu pour ce type de conversion, c'est SandCastle (http://sandcastle.codeplex.com/).

Le plus gros problème, c'est qu'actuellement, ce que fait Eclipse (génération de squelette de commentaire), et bien VS ne le support que sur les langages pur .NET (C#, VB.NET etc...). Il faudra donc faire les XML-Comment à la main (ou bien utiliser un faux projet C# et copier-coller les commentaire XML générés, oui, je suis un très très grand fainéant ).

[saad.hessane]

Je pense que vous m'avez mal compris.
Je ne parle pas de versionement d'application. Je parle de documentation de code source. Doxygen s'utilise toujours aujourd'hui et il est très bien.
Dans ma question j'évoque deux choses. La première est le fait d'écrire la documentation dans le code sous forme de commentaire (en utilisant les conventions de Doxygen par exemple ou dans un autre format peut importe), et la deuxième c'est de générer à partir de cela une documentation pour le projet (solution?). Eclipse fait très bien les deux. Il génère un squelette de documentation pour les méthodes que je crée, et permet grâce à JavaDoc de la JDK de générer une doc au format HTML.
Ça m'étonnerai de ne pas avoir cela avec VS 2010. C'est très pratique et évite de faire du copier coller. Après pour générer la doc au format HTML je peux toujours passer ça à Doxygen.
En cherchant un peu plus sur internet, j'ai trouvé GhostDoc. Il génère une documentation à la XML (c'est de ça dont tu parle quand tu parle des XML Comment ??) à ce que j'ai pu remarqué dans la vidéo suivante :

Mais j'ai essayé de voir le site du plugin, et la licence est gratuite pour utilisation individuel (ce qui n'est pas mon cas).
La génération de documentation au format HTML ou PDF n'est pas là pour faire de la lèche au CP (en tout cas pas dans notre cas). Elle est très utile lorsqu'on fournit une API multiplateforme, qui peut être tester par des développeurs sous Linux et utilisant VI ou emacs (pas d'Intellisence cette fois).

[EDIT] : En regardant d'un peu plus prêt le site de GhostDoc, je remarque qu'il ne supporte que C# et VB .Net. Mais c'est un peu dans le sens de ce que je demande.
A défaut d'avoir une solution qui pré-remplirait les champs de documentation d'une fonction, peut on configurer dans Visual Studio une combinaison de touches (un raccourci quoi) pour qu'il insère un texte prédéfinit?

[bacelar]

Je parle de documentation de code source.

Heu, c'est vous qui avez parlé du change tracking.

Du genre quand on crée un nouveau fichier source il insère automatiquement en haut le nom du développeur, le nom du fichier et une description

Ou j’ai mal compris ?

Doxygen s'utilise toujours aujourd'hui et il est très bien.

Si vous utilisez déjà Doxygen pour la génération de la la documentation, je comprend plus le sens de votre question.

Dans ma question j'évoque deux choses. La première est le fait d'écrire la documentation dans le code sous forme de commentaire (en utilisant les conventions de Doxygen par exemple ou dans un autre format peut importe),

Bin pourquoi changer si vous utilisez Doxygen ?
Sinon, dans l'écosystème VS, on utilise les commentaires avec un format très proche de ceux de Doxygen : des XML Comments.

la deuxième c'est de générer à partir de cela une documentation pour le projet (solution?). Eclipse fait très bien les deux. Il génère un squelette de documentation pour les méthodes que je crée, et permet grâce à JavaDoc de la JDK de générer une doc au format HTML.

Bin, Doxygen il fait pas pareil ?
Sinon, les outils comme SandCastel (et tout les outils au dessus de SandCastel) utilise le fichier XML généré par VS pour faire ce type de documentation, avec différent formats et layout.

Je ne vous pas précisément le problème. Pouvez-vous l'expliciter.

Ça m'étonnerai de ne pas avoir cela avec VS 2010. C'est très pratique et évite de faire du copier coller. Après pour générer la doc au format HTML je peux toujours passer ça à Doxygen.

Toujours ma satané question, si Doxygen marche quel est ses limitations que vous cherchez à dépasser.

En cherchant un peu plus sur internet, j'ai trouvé GhostDoc. Il génère une documentation à la XML (c'est de ça dont tu parle quand tu parle des XML Comment ??) à ce que j'ai pu remarqué dans la vidéo suivante :

GhostDoc est un outil qui simplifie la création des XML Comments dans des cas bien définis, mais assez courant. Il prend aussi la place de SandCastle comme outil de conversion du fichier xml sortie de VS pour en faire une documentation "hors code".

La génération de documentation au format HTML ou PDF n'est pas là pour faire de la lèche au CP (en tout cas pas dans notre cas). Elle est très utile lorsqu'on fournit une API multiplateforme, qui peut être tester par des développeurs sous Linux et utilisant VI ou emacs (pas d'Intellisence cette fois).

Coder avec VI.
Je l'ai fait et je j'ai rapidement gagnez en productivité en faisant un montage SAMBA et utiliser VS simplement pour avoir IntelliSense.
Et je pense qu'un vrai développeur Linux connait des outils qui ont la même "feature" qu'IntelliSense (développeur et pas un geek sur fond noir, police verte à la MATRIX, clavier SVORAK, et tappant sur un clavier à la vitesse d'une Gatling).
Donc le vrai problème, serait un format pivot entre les outils VS et Linux : un convertisseur fichier XML IntelliSense en un autre format ad hoc.
J'insiste, format PDF et HTML, c'est pour faire de la lèche, et en plus ça prend énormément de temps à générer (pour que dalle ).

Si les fonctionnalités de GhostDoc vous intéressent, c'est peut-être pour les aspects génération "automatique" des commentaires ? Alors il faut vous pencher sur les snippets de VS. Assez peux fournis pour C++ mais il y aura peut-être assez pour vos besoins. Sinon, il y a toujours le "faite le vous même".

Pour être efficace, pouvez-vous explicite de manière plus précise vos besoins et les limitations des outils que vous utilisez actuellement ?

[saad.hessane]

Vous vous obstinez à penser que je veux faire du versionnement, alors que tout ce que je veux c'est écrire de la doc plus rapidement. Il est d'usage d'écrire en haut de chaque fichier source une petit copyright, mentionnant la date de création du fichier, et son créateur. Cela va aussi être enregistré dans sur le track c'est sûre, mais ça n'est que l'usage qui le veut. Et personnellement je ne trouve pas ça inutile.
Maintenant DOxygen est extra justement. Mais comme je viens d'un monde où l'IDE Eclipse règne en rois, il y a plusieurs petites choses simples auquels on n'y pense pas au départ mais qui font vraiment toutes l'utilité d'utiliser un IDE au lieu d'un bête éditeur de texte. Parmi ces petits trucs justement c'est de pouvoir définir un modèle pour mes fichiers sources nouvellement créé, ou insérer un commentaire au format JavaDoc avant une fonction qu'on aura plus qu'à remplir.
Exemple :

Code java :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
int methode(){
    return valeur;
}

Deviens :

Code java :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
6
7
/**
  * TODO
  * @param parametre1
  * @return */
int methode(int parametre1){
    return valeur;
}

A la manière dont vous me répondez je dirais que la prochaine solution que vous me proposerez serait que je passe sous Eclipse pour faire du C++...
Si Visual Studio permet d'insérer du texte à l'aide de raccourci clavier ça sera déjà une solution à mon premier problème(là aussi ne me parlez pas de copier coller...).
Maintenant question de génération de documentation, si on opte pour la syntaxe Doxygen y a pas de souci. Si vous me dite qu'il y a un autre type de documentation qui pourrait être efficace aux autres développeurs Visual Studio pourquoi pas. Mais l'essentiel est de mettre en place un système qui rendra l'écriture et la génération de doc intuitif et automatique. Et tout cela pour la simple raison que pour un développeur écrire de la doc est tout simplement barbant.
Pour votre idée sur la doc HTML, je ne suis tout simplement pas d'accord. En disant cela tu insultes la doc Qt, MSDN, et pas seulement en C++ mais dans tous les langages. Une doc HTML est tout sauf inutile (ou utile à faire la lèche). C'est un support que l'on peut facilement mettre en ligne ou en réseau locale pour être accéssible à tous les développeurs. C'est peut être long à générer, mais c'est utile. Et quand c'est bien fait, c'est un gage de qualité du produit.

[saad.hessane]

Je n'ai pas vu à la première lecture les chapitre qui parle de SandCastle. Je le trouve très bien merci.
Vous parlez aussi de snippets de VS?? Merci de m'en dire un peu plus.

[bacelar]

Vous vous obstinez à penser que je veux faire du versionnement, alors que tout ce que je veux c'est écrire de la doc plus rapidement. Il est d'usage d'écrire en haut de chaque fichier source une petit copyright, mentionnant la date de création du fichier, et son créateur. Cela va aussi être enregistré dans sur le track c'est sûre, mais ça n'est que l'usage qui le veut. Et personnellement je ne trouve pas ça inutile.

Vous vous obstinez à vouloir doublonner (de manière non fiable en plus) des informations qui doivent être dans l'outil de GCL.
C'est un usage rependu qui n'a plus de justification avec les outils de GCL modernes.

Maintenant DOxygen est extra justement. Mais comme je viens d'un monde où l'IDE Eclipse règne en rois, il y a plusieurs petites choses simples auquels on n'y pense pas au départ mais qui font vraiment toutes l'utilité d'utiliser un IDE au lieu d'un bête éditeur de texte. Parmi ces petits trucs justement c'est de pouvoir définir un modèle pour mes fichiers sources nouvellement créé,

C'est le rôle de SandCastle.

ou insérer un commentaire au format JavaDoc avant une fonction qu'on aura plus qu'à remplir.
Exemple :

Code java :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
int methode(){
    return valeur;
}

Deviens :

Code java :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
6
7
/**
  * TODO
  * @param parametre1
  * @return */
int methode(int parametre1){
    return valeur;
}

C'est là que C++ est le parent pauvre par rapport au C#.
Cette génération se base sur des snippets qui correspondent à du code chargé dans VS, qui génère du texte (code source ou commentaire) quand il est déclenché en fonction du texte sélectionné ou adjacent au caret. Le déclenche prend plusieurs formes (séquence de caractère, entré dans certain menus contextuels de VS, etc. ; voir la documentation sur les snippets dans MSDN).
Le hic, c'est que la majorité des snippets fournis avec VS cible C# et VB.NET.
Il faudrait donc redéfinir ces snippets dont celui de génération automatique d'un début de documentation d'une classe ou d’une méthode (mais je ne suis pas sûr que pour un langage nom managé, on ait assez d'info pour tout générer dont les exceptions lancés.

Mais des outils tiers, comme AtomineerUtils (http://www.atomineerutils.com/products.php) ont fait ce travail, semble t-il ?

A la manière dont vous me répondez je dirais que la prochaine solution que vous me proposerez serait que je passe sous Eclipse pour faire du C++...
Si Visual Studio permet d'insérer du texte à l'aide de raccourci clavier ça sera déjà une solution à mon premier problème(là aussi ne me parlez pas de copier coller...).

copier coller, c'est mal, c'est le démon. (C'est pas de l'antiphrase).
AtomineerUtils contient-il les fonctionnalités qui vous intéressent ? Sinon, indiquez nous CLAIREMENT ce que vous cherchez. (génération de version initiale de XML Comment, génération de Doc au format Html , autes ?).

Maintenant question de génération de documentation, si on opte pour la syntaxe Doxygen y a pas de souci. Si vous me dite qu'il y a un autre type de documentation qui pourrait être efficace aux autres développeurs Visual Studio pourquoi pas. Mais l'essentiel est de mettre en place un système qui rendra l'écriture et la génération de doc intuitif et automatique. Et tout cela pour la simple raison que pour un développeur écrire de la doc est tout simplement barbant.

D'accord à 100%, mais la partie de la documentation qui est dans le code, elle doit être accessible dans IntelliSense, dans la Doc Html, c'est juste un élément de la documentation. Dans MSDN, c'est les explications et les exemples qui sont intéressants. La partie auto-générable n'a d'intérêt qu'à l'extérieur de VS (et un Développeur Windows et toujours dans VS, même pour accéder à la GCL ou aux outils d'ALM).

Pour votre idée sur la doc HTML, je ne suis tout simplement pas d'accord. En disant cela tu insultes la doc Qt, MSDN, et pas seulement en C++ mais dans tous les langages. Une doc HTML est tout sauf inutile (ou utile à faire la lèche). C'est un support que l'on peut facilement mettre en ligne ou en réseau locale pour être accéssible à tous les développeurs. C'est peut être long à générer, mais c'est utile. Et quand c'est bien fait, c'est un gage de qualité du produit.

Cette documentation doit contenir bien plus que la partie embarqué dans les fichiers sources pour qu'elle ait un intérêt.

Il y a un nombre incalculable de documentation qui ne contient que ces informations (pas d'exemples, pas d'information architecturales etc.) et elles ne présentent AUCUN intérêts si ces informations sont dans IntelliSense.

[saad.hessane]

Merci bacelar, sujet résolue

[bacelar]

Heu, alors je l'ai pas fait exprès.

Vous utilisez AtomineerUtils ou un autre outil ou vous ne faites plus de génération de doc ou ...

Partagez avec la communauté, SVP.

[saad.hessane]

D'accord, je résume. Il me fallait un plugin ou une fonctionnalité Visual Studio pour générer une entête de documentation de fonction. Vous m'avez mis sur la route d'AtomineerUtils. Je pense que ses fonctionnalités me suffisent.
Pour ce qui est de la génération de documentation technique je pense faire passer le tout à Doxygen, ou à SandCastle. Cela dépendra de la syntaxe adopté pour la doc.
Je teste en ce moment même l'utilisation de tout cela. Et jusqu'à maintenant je pense qu ça tient la route.
Dans tous les cas merci beaucoup bacelar, j'avais fait plusieurs recherches avant de poster, sans jamais trouvé ces outils