Qu'écrire dans la documentation de son projet ?
Un article de Sweetydoc.
Voici un modèle pour la présentation de son module. Ce modèle n'est pas figé dans sa forme ou dans son fond et vous êtes libre de la rédaction de votre documentation. Néanmoins il essaye de couvrir l'essentiel de ce qu'une documentation doit impérativement contenir pour être efficiente.
Ce modèle peut aussi être amélioré, n'oubliez pas que tous les developpeurs peuvent l'éditer.
Sommaire |
Partie I : carte d'identité
Nom : nom de code du module (exemple gesdata pour le gestionnaire de profil)
Fonction : fonction attendue du module
Ne rajoutez pas des informations qui vont facilement changer comme les membres de l'equipe ou la version actuelle, elles peuvent être trouvées ailleurs.
Dépendances : les imports réalisés par le module
Partie II : description globale
UML
Poster ici l'image de l'UML ou un lien vers celui-ci
Liste des fonctions
Liste des fonctions qui composent le module et leurs buts. A écrire même si c'est redondant avec l'UML, je rappelle que les images ne sont pas accessibles aux handicapés.
fonction(arg1, arg2=defaut, [arg-optionnel]) avec un lien hypertexte sur la description détaillée ci-dessous.
Liste des classes
Liste des classes qui composent le module et leurs buts.
Classe(arg1, arg2=defaut, [arg-optionnel]) avec un lien hypertexte sur la description détaillée ci-dessous.
Héritage : classes dont hérite la classe
Polymorphisme : méthodes de la classe qui remplacent celles héritées
But : utilité de la classe
Partie III : descritption détaillées
Fonctions
Pour chaque fonction (for x in function_list ;-) ) :
fonction(arg1, arg2=defaut, [arg-optionnel])
Accepte : le type de données (chaine, liste, tuple...) que chaque argument accepte
Processus : Ce que fait la fonction
Retourne : le contenu et le type de données que la fonction retourne (même si c'est None ou un boléen)
Exemple d'utilisation :
>>> ma_fonction(super=elle, genial=1) # petit commentaire qui va bien retour de la fonction
Classes
Reprendre classe par classe, méthode par méthode le module :
Classe : nom de a classe dont on présente les méthodes
__init__
Description du processus d'initialisation
Ensuite pour chaque méthode :
ma_méthode(arg1, arg2=defaut, [arg-optionnel])
Accepte : le type de données (chaine, liste, tuple...) que chaque argument accepte
Processus : Ce que fait la methode
Retourne : le contenu et le type de données que la fonction retourne (même si c'ets None ou un boléen)
Exemple d'utilisation :
objet.ma_methode(super=elle, genial=1) # explication sur l'effet de la méthode
Partie IV : Autres fichiers
Si votre module utilise d'autres fichiers (base de données, fichier .ini pour la configuration, fichier XML...), ils doivent être décris ici.
Fichier 1
nom : nom du fichier
type : type du fichier
chemin d'accès : où trouver le fichier
utilisation : but du fichier
struture : si le fichier est un fichier texte, en décrire la structure
Partie V : How To
Explication des opérations les plus courantes qu'on peut faire du module. Illustration et exemple de ce que les autres developpeurs auront à taper pour profiter des fonctions que vous avez coder.
Pour....
But : le but de la manoeuvre (par exemple obtenir une valeur du module)
Fontion à utiliser : nom de la fonction, lien hypertexte vers sont explication précédente.
# un exemple import mon_module objet = class_de_mon_module() objet.method() # commentaire indispensable sur le résultat
Parties VI : Notes
Explications des choses à faire et ne pas faire avec le module.
Explications de certaines décisions (j'ai codé cela ainsi car je ne pouvais / voulais pas...).
Bugs connus mais non corrigés / correctibles.
Petit mot de la fin.
