Conventions de rédaction de documentation dans le wiki itrocks.org
-
Avant de contribuer à ce wiki, il faut apprendre et se préparer à appliquer strictement les règles énoncées dans ce document, qu’il est conseillé d’imprimer et garder près de soi pendant la rédaction de documentations.
Vocabulaire
- Attribut HTML : attribut d’une balise HTML (attribute)
- Champ : le nom d’un champ dans une structure de table de base de données ou dans un fichier structuré (column), dans un formulaire côté vue (field)
- Classe : déclaration d’une classe d’objets, regroupant ses membres, méthodes, propriétés communs à plusieurs objets (class)
- Constante : dans un contexte global, local ou dans une classe, stocke une valeur invariante (constant)
- Dossier : lieu de stockage de fichiers (directory)
- Elément HTML : élément dans un document HTML (element)
- Fichier : stocke des données sur le disque dur (file)
- Fonction : fonction déclarée globalement, donc hors contexte objet (function)
- Méthode : fonction dans une classe, donc dans un contexte objet (method)
- Objet : l’instance d’une classe (valeur), contenant les données stockées dans une structure correspondant à une classe (object)
- Paramètre : variable envoyée à une fonction / méthode, ou à un script
- Propriété : variable d’une classe (property)
- Valeur de retour : valeur retournée par une fonction / méthode
- Variable : variable déclarée globalement ou localement, donc hors contexte objet (variable)
Par souci d’uniformisation, il ne faut pas employer les mots suivants, mais les remplacer par leur synonyme dans la liste ci-dessus (liste non exhaustive) : argument, balise HTML, répertoire.
Eléments issus du code
- attribut HTML :
name
- chemin de propriété :
property.path
- classe :
Class_Name
- constante globale :
CONSTANT_NAME
- constante numérique :
123
- constante php :
true
(par exemple) - constante texte :
'constante'
- élément du langage PHP (exemples) :
array
,function
- élément HTML :
span
- fonction globale :
functionName()
- fonction php :
function_name()
- méthode d’une classe :
methodName()
- mot réservé du langage PHP (exemples) :
array
,function
- opérateur : par exemple
.
,+
,*
, … - propriété d’une classe :
$property_name
- variable locale ou globale :
$var_name
Lorsqu’un élément issu du code est aussi un lien vers un autre article (interne ou externe au wiki), inutile de préciser le tag de code @, simplement le référencer comme un lien.
Eléments des templates / gabarits
- élément à afficher :
{displayable.data}
- élément de structure (boucle, condition) :
<!--structureElement-->
- portion de code HTML (exemples) :
<!--
,-->
Autres éléments
- chemin d’accès absolu à un dossier : full/path/of/directory
- chemin d’accès absolu à un fichier : /full/path/of/file.txt
- chemin d’accès relatif à un dossier : path/of/directory/
- chemin d’accès relatif à un fichier : path/of/file.txt
- nom d’un dossier : directory/
- nom d’un fichier : file-name.txt