Documenter son code avec VVDocumenter

skimpy · juillet 2013

Bonjour,

Je suis tombé par hasard sur le plugin VVDocumenter (https://github.com/onevcat/VVDocumenter-Xcode) qui permet de générer, entre autre, la documentation d'une métode, à savoir son rôle, les paramètres, la valeur de retour ; et tout ça, simplement en tapant ///

AliGator · juillet 2013

Pas mal en effet, pour en un clin d'oe“il générer la headerdoc avec tous les paramètres rentrés !

Un petit coup de headerdoc2html ou appledoc derrière et hop

Je testerai ce plugin en rentrant, tiens

(j'espère qu'il est compatible Xcode5 ?)

Am_Me · juillet 2013

ça à l'air super : Un gain de temps fou

Am_Me · juillet 2013

Par contre je n'ai jamais installé de plugin sur XCode comment on se prend pour :

Build the VVDocumenter-Xcode target in the Xcode project and the plug-in will automatically be installed in~/Library/Application Support/Developer/Shared/Xcode/Plug-ins.

J'ai compiler le projet mais quand j'ai redémarré Xcode et tapé /// ca n'a rien fait

Et je ne trouve pas non plus le répertoire Shared

MAJ : En fait j'ai recompilé et ça a marché

System · août 2013

Génial comme plugin. Mais évidemment on se tape vite la remarque des collègues : "quoi??! mais Visual Studio le fait depuis des lustres !"

Voilà voilà

Larme · août 2013

Doxygen ne marche pas pour XCode/Objective-C ?

AliGator · août 2013

@Larme : Si mais c'est pas la même chose que fait ce Plug-In !

Ce plugin permet justement de te faciliter la vie pour écrire la documentation Doxygen (ou Headerdoc ou Appledoc, selon tes préférences) dans ton code source. Plutôt que de taper toi-même les "@param" et autres "@return" etc dans les commentaires au dessus de ton code, en t'assurant que tu n'as pas fait de faute de frappe en recopiant le nom de tes paramètres, etc... Bah tu tapes juste "///" et dès que tu as tapé le 3e slash le plugin insère automatiquement un modèle pré-rempli de documentation Doxygen-like, donc avec les "@param" déjà pré-remplis avec le nom des paramètres de la méthode que tu documentes, et tout.

Ca n'empêche pas ensuite de passer ton code source ainsi documenté à la moulinette Doxygen ou HeaderDoc ou AppleDoc pour générer la documentation HTML ou le DocSet bien sûr. Ca ne fait que te faciliter la vie au moment de la saisie de la doc-commentaire.

Larme · août 2013

Ah ok. J'avais pas vu la vidéo sur le GitHub...

Une sorte de TextExpander pour XCode en quelque sorte...

Pas mal du coup...

Am_Me · août 2013

J'ai envie de dire que Eclipse et Android Studio font la même

GranDav · août 2013

Je déterre le sujet pour vous dire que le plugin est compatible Xcode5 depuis une petite mise à jour.

Si vous souhaitez rendre un plugin Xcode4 compatible il suffi de modifier le fichier [NomPlugin]-Info.plist et de lui ajouter le paramètre suivant :



<key>DVTPlugInCompatibilityUUIDs</key>

<array>

<string>63FC1C47-140D-42B0-BB4D-A10B2D225574</string>

</array>

Redémarrrez Xcode et bim! Attention cependant cela ne garantie pas que le-dit plugin fonctionne bien.

Mala · août 2013

Ca fonctionne chez vous? Moi après installation je n'ai qu'un champ description lors que je tape ///

AliGator · août 2013

Oui moi ça marche si je tape /// au dessus de la signature d'une méthode (là où je dois mettre les commentaires de documentation de toute façon pour que Headerdoc/Appledoc/Doxygen puisse en faire qqch)

Mala · août 2013

Bon, je cherche mais je vois pas trop ce qui cloche chez moi (Xcode 4.6.3 et OS X 10.8.4). ???

AliGator · août 2013

Ah ben au dessus de @interface, c'est normal, moi aussi je n'ai que Description. C'est normal, tu voudrais qu'il te mette quoi d'autre comme champs ?

Par contre si tu le fais avant une méthode, bah il rajoute la documentation préremplie des paramètres de la méthode, normal quoi.

Mala · août 2013

Oui tu as raison. Suis je bête! Autant pour moi!

samir · septembre 2013

@Aligator : C'est quoi cette déclaration chelou de méthode ? update...NSArrayOf(NSString*))title. ( je veux dire le NSArrayOf...).

AliGator · septembre 2013

Ah oui, ça ce sont des macros persos qui ne servent à rien d'autre qu'augmenter la lisibilité de mes signatures de méthodes, pour savoir (quand on reprend le code plusieurs mois + tard) ce qu'on est sensé mettre comme type d'objets dans nos tableaux

NSArrayOf(x) n'est rien d'autre qu'un NSArray*, sauf qu'avec cette écriture je m'indique à la lecture du code ce que mon tableau est sensé contenir comme type d'objets.

#define NSArrayOf(x) NSArray*

#define NSMutableArrayOf(x) NSMutableArray*

#define NSSetOf(x) NSSet*

#define NSMutableSetOf(x) NSMutableSet*

Par exemple quand je déclare " @property NSArrayOf(NSString*) cities; " je sais à la lecture que j'attend des chaà®nes (les noms des villes) et pas des objets " City* " dans mon tableau, comme je pourrais le croire si je reviens sur mon code dans 3 mois. Du coup quand je (ou qqun d'autre) retombe sur ce code, je risque moins de mettre un objet City au lieu d'une NSString ou de devoir fouiller dans le code pour retrouver ce que je suis sensé mettre

(bon dans ce cas j'aurai mieux fait de nommer ma propriété "cityNames" pour encore + de clareté, mais bon c'est pour l'exemple ^^)

J'ai quelques autres macros que je me suis faites et que j'aime bien, j'en avais parlé ici l'an dernier (mais à l'époque j'avais pas encore enrichi tout ça de NSArrayOf & co

)

Ded · septembre 2013

Et pourquoi pas utiliser une implémentation des generics en Objective C ?

https://github.com/tomersh/Objective-C-Generics

J'ai pas encore essayé, l'idée est bonne, mais ça me gêne d'écrire de l'Objective J

AliGator · septembre 2013

@Ded oui j'avais déjà vu ça quand Mike Ash ou je ne sais plus quel grand ponte d'ObjC avait parlé de l'idée (et tomersh n'a fait que mettre en pratique le code)

L'idée est bonne, après c'est un peu de la bidouille autour du langage, un peu comme les bidouilles qu'apportent les trucs du genre libextobjc.
Je ne suis pas contre, mais j'aimerai un truc plus officiel

Par exemple son code redéclare toutes les méthodes de NS(Mutable)Array et NS(Mutable)Set, pour les redéfinir pour le cas en question. Le jour où les API évoluent, ou un nouveau SDK sort par exemple, (genre, au hasard, le SDK iOS7), s'il y a des nouveautés dans NSArray ou NSSet, la compatibilité est cassée.

Documenter son code avec VVDocumenter

Réponses