Correction et ajout de phpDoc

inc/getdocument.php

@@ -9,13 +9,19 @@
  *  Ce programme est un logiciel libre distribue sous licence GNU/GPL.     *
  *  Pour plus de details voir le fichier COPYING.txt ou l'aide en ligne.   *
 \***************************************************************************/
+
+/**
+ * Gère un cas d'upload trop gros
+ *
+ * Fichier obsolète, à supprimer.
+ * Mais fonction utilisée encore dans medias_detecter_fond_par_defaut()
+ * 
+ * @package SPIP\Medias\Upload
+**/
+
 #
 # Fichier obsolete, a supprimer
 #
-#
-#
-#
-#
 
 if (!defined('_ECRIRE_INC_VERSION')) return;
 
@@ -24,9 +30,15 @@ include_once _DIR_RESTREINT . "inc/documents.php";
 
 include_spip('inc/minipres');
 
-// Erreur appelee depuis public.php (la precedente ne fonctionne plus
-// depuis qu'on est sortis de spip_image.php, apparemment).
-// http://doc.spip.org/@erreur_upload_trop_gros
+ 
+/**
+ * Traite l'erreur d'un upload trop gros
+ * 
+ * L'erreur est appelée depuis public.php et medias_detecter_fond_par_defaut
+ * et affiche un minipres avec la taille limite de documents possibles
+ *
+ * @see minipres()
+**/
 function erreur_upload_trop_gros() {
 	include_spip('inc/filtres');
 	

inc/renseigner_document.php

@@ -10,16 +10,37 @@
  *  Pour plus de details voir le fichier COPYING.txt ou l'aide en ligne.   *
 \***************************************************************************/
 
+/**
+ * Fonctions pour compléter les informations connues d'un document
+ *
+ * @package SPIP\Medias\Renseigner
+**/
+
 if (!defined("_ECRIRE_INC_VERSION")) return;
 
 /**
- * recuperer les infos distantes d'une url,
+ * Récuperer les infos distantes d'une URL,
  * et renseigner pour une insertion en base
- * utilise une variable static car appellee plusieurs fois au cours du meme hit
- * (verification puis traitement)
+ * 
+ * Utilise une variable static car appellée plusieurs fois au cours du même hit
+ * (vérification puis traitement)
  *
+ * Un plugin peut avec le pipeline renseigner_document_distant renseigner
+ * les informations fichier et mode avant l'analyse et traitement par ce plugin,
+ * qui dans ce cas ne les fera pas. Exemple : OEmbed
+ * 
+ * @pipeline_appel renseigner_document_distant
+ * 
  * @param string $source
- * @return string
+ *     URL du document
+ * @return array|string
+ *     Informations sur le fichier distant, sinon message d'erreur.
+ *     Sans erreur, retourne un tableau :
+ *
+ *     - source : URL du fichier
+ *     - distant : Est-ce un fichier distant ?
+ *     - mode : Mode d'inclusion
+ *     - fichier : Chemin local du fichier s'il a été recopié
  */
 function renseigner_source_distante($source){
 	static $infos = array();
@@ -60,15 +81,17 @@ function renseigner_source_distante($source){
  * Ces fonctions de récupérations peuvent retourner d'autres champs si ces champs sont définis
  * comme editable dans la déclaration de la table spip_documents
  * 
- * TODO Renommer cette fonction sans "_image"
+ * @todo
+ *     Renommer cette fonction sans "_image"
  *
  * @param string $fichier 
- * 		Le fichier à examiner 
+ *     Le fichier à examiner 
  * @param string $ext
- * 		L'extension du fichier à examiner
+ *     L'extension du fichier à examiner
  * @return array|string $infos
- * 		Si c'est une chaine, c'est une erreur
- * 		Si c'est un tableau, l'ensemble des informations récupérées du fichier
+ *
+ *     - Si c'est une chaîne, c'est une erreur
+ *     - Si c'est un tableau, l'ensemble des informations récupérées du fichier
  */
 function renseigner_taille_dimension_image($fichier,$ext){
 
@@ -109,4 +132,4 @@ function renseigner_taille_dimension_image($fichier,$ext){
 	return $infos;
 }
 
-?>
\ No newline at end of file
+?>

medias_pipelines.php

@@ -19,9 +19,17 @@
 
 if (!defined('_ECRIRE_INC_VERSION')) return;
 
+/**
+ * Traiter le cas pathologique d'un upload de document ayant echoué
+ * car étant trop gros
+ *
+ * @pipeline detecter_fond_par_defaut
+ * @param string $fond
+ *     Nom du squelette par défaut qui sera utilisé
+ * @return string
+ *     Nom du squelette par défaut qui sera utilisé
+**/
 function medias_detecter_fond_par_defaut($fond){
-	// traiter le cas pathologique d'un upload de document ayant echoue
-	// car trop gros
 	if (empty($_GET) AND empty($_POST) AND empty($_FILES)
 	AND isset($_SERVER["CONTENT_LENGTH"])
 	AND strstr($_SERVER["CONTENT_TYPE"], "multipart/form-data;")) {
@@ -33,11 +41,18 @@ function medias_detecter_fond_par_defaut($fond){
 
 
 /**
- * A chaque insertion d'un nouvel objet editorial
- * auquel on a attache des documents, restituer l'identifiant
- * du nouvel objet cree sur les liaisons documents/objet,
- * qui ont ponctuellement un identifiant id_objet negatif.
- * cf. medias_affiche_gauche()
+ * À chaque insertion d'un nouvel objet editorial
+ * auquel on a attaché des documents, restituer l'identifiant
+ * du nouvel objet crée sur les liaisons documents/objet,
+ * qui ont ponctuellement un identifiant id_objet négatif.
+ * 
+ * @see medias_affiche_gauche()
+ * @pipeline post_insertion
+ * 
+ * @param array $flux
+ *     Données du pipeline
+ * @return array
+ *     Données du pipeline
 **/
 function medias_post_insertion($flux){
 
@@ -67,7 +82,9 @@ function medias_post_insertion($flux){
 }
 
 /**
- * Configuration des contenus
+ * Ajoute la configuration des documents à la page de configuration des contenus
+ *
+ * @pipeline affiche_milieu
  * @param array $flux
  * @return array
  */
@@ -78,13 +95,30 @@ function medias_affiche_milieu($flux){
 	return $flux;
 }
 
+/**
+ * Définir les meta de configuration liées aux documents
+ *
+ * @pipeline configurer_liste_metas
+ * @param array $config
+ *     Couples nom de la méta => valeur par défaut
+ * @return array
+ *    Couples nom de la méta => valeur par défaut
+ */
 function medias_configurer_liste_metas($config){
 	$config['documents_objets'] = '';
 	$config['documents_date'] = 'non';
 	return $config;
 }
 
-
+/**
+ * Institue ou met à jour les liens de documents après l'édition d'un objet
+ *
+ * @pipeline post_edition
+ * @param array $flux
+ *     Données du pipeline
+ * @return array
+ *     Données du pipeline
+**/
 function medias_post_edition($flux){
 	// le serveur n'est pas toujours la
 	$serveur = (isset($flux['args']['serveur']) ? $flux['args']['serveur'] : '');
@@ -126,13 +160,13 @@ function medias_post_edition($flux){
 }
 
 /**
- * Pipeline afficher_complement_objet
- * afficher le portfolio et ajout de document sur les fiches objet
- * sur lesquelles les medias ont ete activees
- * Pour les articles, on ajoute toujours !
+ * Ajouter le portfolio et ajout de document sur les fiches objet
  * 
- * @param  $flux
- * @return
+ * Uniquement sur les objets pour lesquelles les medias ont été activés
+ *
+ * @pipeline afficher_complement_objet
+ * @param array $flux
+ * @return array
  */
 function medias_afficher_complement_objet($flux){
 	if ($type=$flux['args']['type']
@@ -145,16 +179,24 @@ function medias_afficher_complement_objet($flux){
 }
 
 /**
- * Pipeline affiche_gauche
- * Affiche le formulaire d'ajout de document sur le formulaire d'edition
+ * Ajoute le formulaire d'ajout de document au formulaire d'édition
  * d'un objet (lorsque cet objet peut recevoir des documents).
  *
- * HACK : Lors d'une premiere creation de l'objet, celui-ci n'ayant pas
- * encore d'identifiant tant que le formulaire d'edition n'est pas enregistre,
- * les liaisions entre les documents lies et l'objet a creer sauvegardent
- * un identifiant d'objet negatif de la valeur de id_auteur (l'auteur
- * connecte). Ces liaisons seront corrigees apres validation dans
- * medias_post_insertion()
+ * @note
+ *   HACK : Lors d'une première création de l'objet, celui-ci n'ayant pas
+ *   encore d'identifiant tant que le formulaire d'édition n'est pas enregistré,
+ *   les liaisions entre les documents liés et l'objet à créer sauvegardent
+ *   un identifiant d'objet négatif de la valeur de id_auteur (l'auteur
+ *   connecte). Ces liaisons seront corrigées après validation dans
+ *   le pipeline medias_post_insertion()
+ *
+ * @pipeline affiche_gauche
+ * @see medias_post_insertion()
+ * 
+ * @param array $flux
+ *     Données du pipeline
+ * @return array
+ *     Données du pipeline
  */
 function medias_affiche_gauche($flux){
 	if ($en_cours = trouver_objet_exec($flux['args']['exec'])
@@ -173,14 +215,58 @@ function medias_affiche_gauche($flux){
 	return $flux;
 }
 
+/**
+ * Utilisation du pipeline document_desc_actions
+ *
+ * Ne fait rien ici.
+ *
+ * Ce pipeline permet aux plugins d'ajouter de boutons d'action supplémentaires
+ * sur les formulaires d'ajouts de documents
+ *
+ * @pipeline document_desc_actions
+ * @param array $flux
+ *     Données du pipeline
+ * @return array
+ *     Données du pipeline
+**/
 function medias_document_desc_actions($flux){
 	return $flux;
 }
 
+/**
+ * Utilisation du pipeline editer_document_actions
+ *
+ * Ne fait rien ici.
+ *
+ * Ce pipeline permet aux plugins d'ajouter de boutons d'action supplémentaires
+ * sur les formulaires d'édition de documents
+ *
+ * @pipeline editer_document_actions
+ * @param array $flux
+ *     Données du pipeline
+ * @return array
+ *     Données du pipeline
+**/
 function medias_editer_document_actions($flux){
 	return $flux;
 }
 
+/**
+ * Utilisation du pipeline renseigner_document_distant
+ *
+ * Ne fait rien ici.
+ *
+ * Ce pipeline permet aux plugins de renseigner les clés `fichier` et
+ * `mode` d'un document distant à partir de l'URL du fichier dans
+ * la clé `source`.
+ *
+ * @see renseigner_source_distante()
+ * @pipeline renseigner_document_distant
+ * @param array $flux
+ *     Données du pipeline
+ * @return array
+ *     Données du pipeline
+**/
 function medias_renseigner_document_distant($flux){
 	return $flux;
 }
@@ -188,6 +274,7 @@ function medias_renseigner_document_distant($flux){
 /**
  * Compter les documents dans un objet
  *
+ * @pipeline objet_compte_enfants
  * @param array $flux
  * @return array
  */
@@ -207,6 +294,7 @@ function medias_objet_compte_enfants($flux){
 /**
  * Afficher le nombre de documents dans chaque rubrique
  *
+ * @pipeline boite_infos
  * @param array $flux
  * @return array
  */