Aidons PHPDocumentor à trouver les marqueurs TODO :

Il les cherche dans une ligne commençant par 
// TODO description ou
// TODO: description
On homogénéise donc. 

Et dans les docblock, on peut utiliser @todo

On ajoute un phpdoc sur inc/autoriser.

ecrire/action/confirmer_inscription.php

@@ -34,7 +34,7 @@ function action_confirmer_inscription_dist() {
 		auteur_effacer_jeton($auteur['id_auteur']);
 
 		// si pas de redirection demandee, rediriger vers public ou prive selon le statut de l'auteur
-		// TODO : ne semble pas marcher si inscrit non visiteur, a debug
+		// TODO: ne semble pas marcher si inscrit non visiteur, a debug
 		if (!_request('redirect')){
 			// on passe id_auteur explicite pour forcer une lecture en base de toutes les infos
 			if (autoriser('ecrire','','',$auteur['id_auteur'])){

ecrire/action/editer_rubrique.php

@@ -158,7 +158,7 @@ function rubrique_modifier($id_rubrique, $set=null) {
  * que si $confirme_deplace == 'oui', et change alors l'id_rubrique des
  * brèves en question
  * 
- * [todo] À déporter dans le plugin brèves via un pipeline ?
+ * @todo À déporter dans le plugin brèves via un pipeline ?
  *
  * @param int $id_rubrique
  *     Identifiant de la rubrique déplacée

ecrire/inc/acces.php

@@ -170,7 +170,7 @@ function ecrire_acces() {
 	# remarque : ici on laisse passer les "nouveau" de maniere a leur permettre
 	# de devenir redacteur le cas echeant (auth http)... a nettoyer
 	// attention, il faut au prealable se connecter a la base (necessaire car utilise par install)
-	# TODO : factoriser avec auth/spip qui fait deja ce job et generaliser le test spip_connect_ldap()
+	// TODO: factoriser avec auth/spip qui fait deja ce job et generaliser le test spip_connect_ldap()
 
 	if (spip_connect_ldap()) return;
 	$p1 = ''; // login:htpass pour tous

ecrire/inc/autoriser.php

@@ -10,19 +10,33 @@
  *  Pour plus de details voir le fichier COPYING.txt ou l'aide en ligne.   *
 \***************************************************************************/
 
+/**
+ * Gestion de l'API autoriser et fonctions d'autorisations de SPIP
+ *
+ * @package SPIP\Autorisations
+**/
 if (!defined('_ECRIRE_INC_VERSION')) return;
 
 include_spip('base/abstract_sql');
 
-# faut-il tracer les autorisations dans tmp/spip.log ?
+/**
+ * Tracer les autorisations dans tmp/spip.log pour débug ?
+ */
 defined('_DEBUG_AUTORISER') || define('_DEBUG_AUTORISER', false);
 
 // Constantes surchargeables, cf. plugin autorite
-// false pour ignorer la notion d'admin restreint # todo: une option a activer
+
+/**
+ * Gérer les admins restreints ?
+ * 
+ * @todo une option à activer
+ */
 defined('_ADMINS_RESTREINTS') || define('_ADMINS_RESTREINTS', true);
-// statut par defaut a la creation
+
+/** Statut par defaut à la creation */
 defined('_STATUT_AUTEUR_CREATION') || define('_STATUT_AUTEUR_CREATION', '1comite');
-// statuts associables a des rubriques (separes par des virgules)
+
+/** statuts associables a des rubriques (separes par des virgules) */
 defined('_STATUT_AUTEUR_RUBRIQUE') || define('_STATUT_AUTEUR_RUBRIQUE', _ADMINS_RESTREINTS ? '0minirezo' : '');
 
 // mes_fonctions peut aussi declarer des autorisations, donc il faut donc le charger
@@ -32,9 +46,42 @@ if ($f = find_in_path('mes_fonctions.php')) {
 }
 
 
-// surcharge possible de autoriser(), sinon autoriser_dist()
+/**
+ * Autoriser une action
+ * 
+ * Teste si une personne (par défaut le visiteur en cours) peut effectuer
+ * une certaine action. Cette fonction est le point d'entrée de toutes
+ * les autorisations.
+ *
+ * La fonction se charge d'appeler des fonctions d'autorisations spécifiques
+ * aux actions demandées si elles existent. Elle cherche donc les fonctions
+ * dans cet ordre :
+ * - autoriser_{type}_{faire}, sinon avec _dist
+ * - autoriser_{type}, sinon avec _dist
+ * - autoriser_{faire}, sinon avec _dist
+ * - autoriser_{defaut}, sinon avec _dist
+ * 
+ * Seul le premier argument est obligatoire
+ *
+ * @api
+ * @see autoriser_dist()
+ * 
+ * @param string $faire
+ *   une action ('modifier', 'publier'...)
+ * @param string $type
+ *   type d'objet ou nom de table ('article')
+ * @param int $id
+ *   id de l'objet sur lequel on veut agir
+ * @param null|int|array $qui
+ *   - si null on prend alors visiteur_session
+ *   - un id_auteur (on regarde dans la base)
+ *   - un tableau auteur complet, y compris [restreint]
+ * @param null|array $opt
+ *   options sous forme de tableau associatif
+ * @return bool
+ *   true si la personne peut effectuer l'action
+ */
 if (!function_exists('autoriser')) {
-// http://doc.spip.org/@autoriser
 	function autoriser() {
 		// Charger les fonctions d'autorisation supplementaires
 		static $pipe;
@@ -47,13 +94,12 @@ if (!function_exists('autoriser')) {
 
 
 /**
- * API pour une fonction generique d'autorisation :
- * (par exemple pour preciser si l'autorisation concerne tel ou tel champ)
- *
- * Seul le premier argument est obligatoire
- *
- * http://doc.spip.org/@autoriser_dist
- *
+ * Autoriser une action
+ * 
+ * Voir autoriser() pour une description complète
+ * 
+ * @see autoriser()
+ * 
  * @param string $faire
  *   une action ('modifier', 'publier'...)
  * @param string $type
@@ -67,6 +113,7 @@ if (!function_exists('autoriser')) {
  * @param null|array $opt
  *   options sous forme de tableau associatif
  * @return bool
+ *   true si la personne peut effectuer l'action
  */
 function autoriser_dist($faire, $type='', $id=0, $qui = NULL, $opt = NULL) {
 

ecrire/inc/filtres_images_lib_mini.php

@@ -253,7 +253,7 @@ function _image_valeurs_trans($img, $effet, $forcer_format = false, $fonction_cr
 			reconstruire_image_intermediaire($fichier);
 		}
 	}
-	// todo: si une image png est nommee .jpg, le reconnaitre avec le bon $f
+	// TODO: si une image png est nommee .jpg, le reconnaitre avec le bon $f
 	$ret["fonction_imagecreatefrom"] = "_imagecreatefrom".$term_fonction;
 	$ret["fichier"] = $fichier;
 	$ret["fonction_image"] = "_image_image".$terminaison_dest;

ecrire/inc/install.php

@@ -29,8 +29,8 @@ if (!defined('_ECRIRE_INC_VERSION')) return;
  * @example
  *     install_fichier_connexion(_FILE_CONNECT_TMP, $contenu);
  * 
- * @internal
- *     [todo] Renommer cette fonction qui peut servir à d'autres utilisations ?
+ * @todo
+ *     Renommer cette fonction qui peut servir à d'autres utilisations ?
  * 
  * @param string $nom
  *     Chemin du fichier à créer

ecrire/inc/rechercher.php

@@ -184,7 +184,7 @@ function recherche_en_base($recherche='', $tables=NULL, $options=array(), $serve
 
 		spip_timer('rech');
 
-		# TODO : ici plutot charger un iterateur via l'API iterateurs
+		// TODO: ici plutot charger un iterateur via l'API iterateurs
 		include_spip('inc/recherche_to_array');
 		$to_array = charger_fonction('recherche_to_array', 'inc');
 		$results[$table] = $to_array($recherche,

ecrire/public/iterateur.php

@@ -212,7 +212,7 @@ class IterDecorator extends FilterIterator {
 	private function calculer_filtres() {
 		
 		// Issu de calculer_select() de public/composer L.519
-		// [todo] externaliser...
+		// TODO: externaliser...
 		//
 		// retirer les criteres vides:
 		// {X ?} avec X absent de l'URL
@@ -285,7 +285,7 @@ class IterDecorator extends FilterIterator {
 				return;
 			}
 		}
-		# [todo ?] analyser le filtre pour refuser ce qu'on ne sait pas traiter ?
+		// TODO: analyser le filtre pour refuser ce qu'on ne sait pas traiter ?
 		# mais c'est normalement deja opere par calculer_critere_infixe()
 		# qui regarde la description 'desc' (en casse reelle d'ailleurs : {isDir=1}
 		# ne sera pas vu si l'on a defini desc['field']['isdir'] pour que #ISDIR soit present.

ecrire/req/sqlite_generique.php

@@ -19,7 +19,7 @@
  
 if (!defined('_ECRIRE_INC_VERSION')) return;
 
-# todo : get/set_caracteres ?
+// TODO: get/set_caracteres ?
 
 
 /*