Modèle de description des méthodes
Pour décrire les différentes méthodes d'une classe (dans des pages séparées), je (
LordFarquaad) propose le modèle suivant (inspiré de php.net):
On commence par un trail pour une navigation facile
{{trail toc="ClasseNomDeLaClasse"}}
Methode : NomDeLaMethode
(n'oubliez pas les guillemets doubles pour ne pas créer un lien, car votre méthode ne doit pas être détaillée dans la page NomDeLaMethode mais dans la page ClasseNomDeLaClasseMethodeNomDeLaMethode, par exemple
ClasseWikiMethodeQuery)
ClasseNomDeLaClasse (lien vers la page de la classe concernée, par exemple
ClasseWiki)
WikiNi "
version de WikiNi à partir de laquelle la méthode est disponible" (exemple: "
WikiNi >= 0.4.3")
Dépréciée depuis "
version de WikiNi à partir de laquelle la méthode n'est plus utilisée" (le cas échéant) Par exemple: "
Dépréciée depuis WikiNi 0.4.2 - ne l'utilisez pas ! Utilisez la méthode NomDeLaNouvelleMethode"
Résumé : copie du résumé placé à la page ClasseNomDeLaClasse
Description :
ReturnType NomDeLaMethode( [
type NomArgument1 [, ...]] )
où vous remplacez
ReturnType par le type de valeurs retournés ("
void" si la méthode ne retourne aucune valeur) et
type par le type d'argument à donner. Si plusieurs types sont possibles, utilisez "
mixed". Vous pouvez mettre les arguments facultatifs entre crochets.
- je pense qu'il est préférable d'utiliser les noms anglais pour les types, je crains qu'en français cela porte à confusion... et puis toutes les méthodes sont déjà nommées en anglais etc. donc dans la continuité, ça me aparaît normal -- LordFarquaad
Description détaillée de la méthode et de son utilisation...
Voir aussi : noms des éventuelles méthodes, classes, fonctions et autres pages en rapport avec celle-ci.
On pourrait éventuellement mettre un {{backlinks}} aussi...
Un deuxième trail:
{{trail toc="ClasseNomDeLaClasse"}}
Suggestions de développement :
On parle ici des améliorations possibles pour la méthode en question: performances, fonctionnement, bugs etc.
- Pour de l'assistance au développement je propose d'utiliser les commentaires, sinon à quoi servent-ils ?
- Justement... ça fait longtemps qu'on se pose la question. Il y a pas mal de monde qui voudrait les voir supprimer. Pour qu'ils soient intéressants, il faudrait au moins les intégrer aux DerniersChangements. En tous cas ils risquent fort de ne pas être lus (perso, je les lis assez peu...). -- CharlesNepote
Merci de garder la partie avant ces deux traits telle quelle, et de discuter de son amélioration ci-dessous.
Discussions concernant le modèle de description des méthodes
Je vois bien l'exemple de la page
ClasseWikiMethodeLoadSingle : c'est vraiment très bien ! J'adhère à fond. Une petite remarque : il y a beaucoup de traits et 2 trails sont-ils vraiment indispensables ? Cf. mon exemple
ExClasseWikiMethodeLoadSingle. --
CharlesNepote
- Euh... pour les deux derniers traits c'était pour marquer la fin de l'exemple, il ne faut pas les recopier ;-) Sinon trois traits ça va encore il me semble (deux si on ne met pas le deuxième trail), je trouve que ça fait plus propre, notemment pour marquer la différence entre l'aide et les discussions... (mais c'est vrai qu'à la limite ça pourrait être encore une page séparée...)
- Pour les trails je trouve pratique d'en mettre un au dessus et un en dessous, parce que la description peut devenir assez longue je pense (avec des exemples entre balises de code etc.), mais bon on peut n'en mettre qu'un, c'est comme un veut... Tiens c'est bizarre l'effet du trail :-S En fait il faudrait écrire la page de description de la classe sous la forme - [[ClasseMachinMethodeTruc function Truc]] normalement... argh ouais en fait ça ne marche pas, il faut que je remodifie la page ClasseWiki...
Je voudrais surtout pas vous décourager de faire une si bonne documentation bien détaillée pour les développeurs, mais attention... Cette documentation il va falloir la maintenir ensuite ! Et je ne compte pas m'y coller... J'hésite déjà souvent à faire des développements vu que j'oublie à chaque fois les pages où je dois indiquer ce que j'ai fait... Si on en ajoute encore, je ne vais probablement plus développer du tout... :-( Merci au moins de respecter le modèle choisi pour la documentation qui impose d'indiquer dans le nom de page le numéro de version de
WikiNi concerné. --
ProgFou