From 7f185f84419d20bc4e98ff5c03c279cb580eeb4d Mon Sep 17 00:00:00 2001
From: "marcimat@rezo.net" <>
Date: Sat, 16 Feb 2013 02:05:43 +0000
Subject: [PATCH] Correction et ajout de phpDoc
---
action/ajouter_documents.php | 91 +++++++++-------
action/dissocier_document.php | 17 ++-
action/verifier_documents_liens.php | 13 ++-
formulaires/joindre_document.php | 2 +-
medias_autoriser.php | 155 +++++++++++++++++++---------
5 files changed, 187 insertions(+), 91 deletions(-)
diff --git a/action/ajouter_documents.php b/action/ajouter_documents.php
index aa7d3897..5d14a491 100644
--- a/action/ajouter_documents.php
+++ b/action/ajouter_documents.php
@@ -10,6 +10,12 @@
* Pour plus de details voir le fichier COPYING.txt ou l'aide en ligne. *
\***************************************************************************/
+/**
+ * Gestion de l'action ajouter_documents
+ *
+ * @package SPIP\Medias\Action
+**/
+
if (!defined("_ECRIRE_INC_VERSION")) return;
include_spip('inc/getdocument');
@@ -21,18 +27,18 @@ include_spip('inc/renseigner_document');
* Ajouter des documents
*
* @param int $id_document
- * document a remplacer, ou pour une vignette, l'id_document de maman
+ * Document à remplacer, ou pour une vignette, l'id_document de maman
* 0 ou 'new' pour une insertion
- * @param $files
- * tableau de taleau de propriete pour chaque document a inserer
- * @param $objet
- * objet auquel associer le document
- * @param $id_objet
+ * @param array $files
+ * Tableau de taleau de propriété pour chaque document à insérer
+ * @param string $objet
+ * Objet auquel associer le document
+ * @param int $id_objet
* id_objet
- * @param $mode
- * mode par defaut si pas precise pour le document
+ * @param string $mode
+ * Mode par défaut si pas precisé pour le document
* @return array
- * liste des id_documents inseres
+ * Liste des id_documents inserés
*/
function action_ajouter_documents_dist($id_document, $files, $objet, $id_objet, $mode){
$ajouter_un_document = charger_fonction('ajouter_un_document','action');
@@ -52,27 +58,27 @@ function action_ajouter_documents_dist($id_document, $files, $objet, $id_objet,
/**
* Ajouter un document (au format $_FILES)
*
- * http://doc.spip.org/@ajouter_un_document
- *
* @param int $id_document
- * document a remplacer, ou pour une vignette, l'id_document de maman
+ * Document à remplacer, ou pour une vignette, l'id_document de maman
* 0 ou 'new' pour une insertion
* @param array $file
- * proprietes au format $_FILE etendu :
- * string tmp_name : source sur le serveur
- * string name : nom du fichier envoye
- * bool titrer : donner ou non un titre a partir du nom du fichier
- * bool distant : pour utiliser une source distante sur internet
- * string mode : vignette|image|documents|choix
+ * Propriétes au format $_FILE étendu :
+ *
+ * - string tmp_name : source sur le serveur
+ * - string name : nom du fichier envoye
+ * - bool titrer : donner ou non un titre a partir du nom du fichier
+ * - bool distant : pour utiliser une source distante sur internet
+ * - string mode : vignette|image|documents|choix
* @param string $objet
- * objet auquel associer le document
+ * Objet auquel associer le document
* @param int $id_objet
* id_objet
* @param string $mode
- * mode par defaut si pas precise pour le document
+ * Mode par défaut si pas precisé pour le document
* @return array|bool|int|mixed|string|unknown
- * si int : l'id_document ajouté (opération réussie)
- * si string : une erreur s'est produit, la chaine est le message d'erreur
+ *
+ * - int : l'id_document ajouté (opération réussie)
+ * - string : une erreur s'est produit, la chaine est le message d'erreur
*
*/
function action_ajouter_un_document_dist($id_document, $file, $objet, $id_objet, $mode) {
@@ -229,10 +235,14 @@ function action_ajouter_un_document_dist($id_document, $file, $objet, $id_objet,
/**
* Corrige l'extension du fichier dans quelques cas particuliers
- * (a passer dans ecrire/base/typedoc)
- * A noter : une extension 'pdf ' passe dans la requete de controle
- * mysql> SELECT * FROM spip_types_documents WHERE extension="pdf ";
+ *
+ * @note
+ * Une extension 'pdf ' passe dans la requête de contrôle
+ * mysql> SELECT * FROM spip_types_documents WHERE extension="pdf ";
*
+ * @todo
+ * À passer dans base/typedoc
+ *
* @param string $ext
* @return string
*/
@@ -259,13 +269,20 @@ function corriger_extension($ext) {
}
/**
- * Verifie la possibilite d'uploader une extension
- * renvoie un tableau descriptif si l'extension est acceptee
- * avec un index 'autozip' si il faut zipper
- * false ou message d'erreur si l'extension est refusee
- * Verifie aussi si l'extension est autorisee pour le mode demande
- * si on connait le mode a ce moment la
+ * Vérifie la possibilité d'uploader une extension
*
+ * Vérifie aussi si l'extension est autorisée pour le mode demandé
+ * si on connait le mode à ce moment lÃ
+ *
+ * @param string $source
+ * Nom du fichier
+ * @param string $mode
+ * Mode d'inclusion du fichier, si connu
+ * @return array|bool|string
+ *
+ * - array : extension acceptée (tableau descriptif).
+ * Avec un index 'autozip' si il faut zipper
+ * - false ou message d'erreur si l'extension est refusée
*/
function verifier_upload_autorise($source, $mode=''){
$infos = array('fichier'=>$source);
@@ -301,15 +318,19 @@ function verifier_upload_autorise($source, $mode=''){
/**
- * tester le type de document :
+ * Tester le type de document
+ *
* - le document existe et n'est pas de taille 0 ?
* - interdit a l'upload ?
* - quelle extension dans spip_types_documents ?
* - est-ce "inclus" comme une image ?
*
- * le zipper si necessaire
+ * Le zipper si necessaire
*
- * @param array $file //format $_FILES
+ * @param array $file
+ * Au format $_FILES
+ * @param string $mode
+ * Mode d'inclusion du fichier, si connu
* @return array
*/
function fixer_fichier_upload($file, $mode=''){
@@ -430,4 +451,4 @@ function verifier_taille_document_acceptable($infos){
}
-?>
\ No newline at end of file
+?>
diff --git a/action/dissocier_document.php b/action/dissocier_document.php
index af468fc1..04c7fea4 100644
--- a/action/dissocier_document.php
+++ b/action/dissocier_document.php
@@ -10,17 +10,24 @@
* Pour plus de details voir le fichier COPYING.txt ou l'aide en ligne. *
\***************************************************************************/
+/**
+ * Gestion de l'action dissocier_document
+ *
+ * @package SPIP\Medias\Action
+**/
+
if (!defined("_ECRIRE_INC_VERSION")) return;
/**
* Dissocier un document
- * $arg fournit les arguments de la fonction dissocier_document
- * sous la forme
- * $id_objet-$objet-$document-suppr-safe
*
- * 4eme arg : suppr = true, false sinon
- * 5eme arg : safe = true, false sinon
+ * @param string $arg
+ * fournit les arguments de la fonction dissocier_document
+ * sous la forme `$id_objet-$objet-$document-suppr-safe`
+ *
+ * - 4eme arg : suppr = true, false sinon
+ * - 5eme arg : safe = true, false sinon
*
* @return void
*/
diff --git a/action/verifier_documents_liens.php b/action/verifier_documents_liens.php
index 691eea78..ba0abea3 100644
--- a/action/verifier_documents_liens.php
+++ b/action/verifier_documents_liens.php
@@ -10,11 +10,20 @@
* Pour plus de details voir le fichier COPYING.txt ou l'aide en ligne. *
\***************************************************************************/
+/**
+ * Gestion de l'action verifier_documents_liens
+ *
+ * @package SPIP\Medias\Action
+**/
+
if (!defined("_ECRIRE_INC_VERSION")) return;
/**
- * Verifier tous les fichiers brises
+ * Vérifier tous les fichiers brisés
*
+ * @param int|null $id_document
+ * Indique le document cible de l'action, sinon il sera
+ * obtenu par la clé d'action sécurisée.
*/
function action_verifier_documents_liens_dist($id_document=null) {
@@ -29,4 +38,4 @@ function action_verifier_documents_liens_dist($id_document=null) {
}
-?>
\ No newline at end of file
+?>
diff --git a/formulaires/joindre_document.php b/formulaires/joindre_document.php
index ab2e60ee..f61c72e1 100644
--- a/formulaires/joindre_document.php
+++ b/formulaires/joindre_document.php
@@ -87,7 +87,7 @@ function formulaires_joindre_document_charger_dist($id_document='new',$id_objet=
$valeurs['editable'] = autoriser('joindredocument',$objet,$id_objet)?' ':'';
}
}
-
+
return $valeurs;
}
diff --git a/medias_autoriser.php b/medias_autoriser.php
index d379af1a..f4342658 100644
--- a/medias_autoriser.php
+++ b/medias_autoriser.php
@@ -10,30 +10,59 @@
* Pour plus de details voir le fichier COPYING.txt ou l'aide en ligne. *
\***************************************************************************/
+/**
+ * Définit les autorisations du plugin Médias
+ *
+ * @package SPIP\Medias\Autorisations
+**/
+
if (!defined('_ECRIRE_INC_VERSION')) return;
-/* Pour que le pipeline de rale pas ! */
+/**
+ * Fonction d'appel pour le pipeline
+ * @pipeline autoriser
+ */
function medias_autoriser(){}
-
-function autoriser_mediatheque_administrer_dist($faire,$quoi,$id,$qui,$options) {
+/**
+ * Autorisation d'administrer la médiathèque
+ *
+ * @param string $faire Action demandée
+ * @param string $type Type d'objet sur lequel appliquer l'action
+ * @param int $id Identifiant de l'objet
+ * @param array $qui Description de l'auteur demandant l'autorisation
+ * @param array $opt Options de cette autorisation
+ * @return bool true s'il a le droit, false sinon
+**/
+function autoriser_mediatheque_administrer_dist($faire,$type,$id,$qui,$opt) {
return $qui['statut'] == '0minirezo';
}
-function autoriser_documents_menu_dist($faire,$quoi,$id,$qui,$options) {
- return autoriser('administrer','mediatheque',$id,$qui,$options);
+/**
+ * Autorisation de voir le bouton Documents dans le menu
+ *
+ * @param string $faire Action demandée
+ * @param string $type Type d'objet sur lequel appliquer l'action
+ * @param int $id Identifiant de l'objet
+ * @param array $qui Description de l'auteur demandant l'autorisation
+ * @param array $opt Options de cette autorisation
+ * @return bool true s'il a le droit, false sinon
+**/
+function autoriser_documents_menu_dist($faire,$type,$id,$qui,$opt) {
+ return autoriser('administrer','mediatheque',$id,$qui,$opt);
}
/**
* Autoriser le changement des dimensions sur un document
- * @param <type> $faire
- * @param <type> $quoi
- * @param <type> $id
- * @param <type> $qui
- * @param <type> $options
- * @return <type>
+ *
+ * @param string $faire Action demandée
+ * @param string $type Type d'objet sur lequel appliquer l'action
+ * @param int $id Identifiant de l'objet
+ * @param array $qui Description de l'auteur demandant l'autorisation
+ * @param array $options Options de cette autorisation
+ * @return bool true s'il a le droit, false sinon
*/
-function autoriser_document_tailler_dist($faire,$quoi,$id,$qui,$options) {
+function autoriser_document_tailler_dist($faire,$type,$id,$qui,$options) {
if (!$id_document=intval($id))
return false;
@@ -68,15 +97,21 @@ function autoriser_document_tailler_dist($faire,$quoi,$id,$qui,$options) {
}
/**
+ * Autorisation de joindre un document
+ *
* On ne peut joindre un document qu'a un objet qu'on a le droit d'editer
* mais il faut prevoir le cas d'une *creation* par un redacteur, qui correspond
* au hack id_objet = 0-id_auteur
+ *
* Il faut aussi que les documents aient ete actives sur les objets concernes
* ou que ce soit un article, sur lequel on peut toujours uploader des images
*
- * http://doc.spip.org/@autoriser_joindredocument_dist
- *
- * @return bool
+ * @param string $faire Action demandée
+ * @param string $type Type d'objet sur lequel appliquer l'action
+ * @param int $id Identifiant de l'objet
+ * @param array $qui Description de l'auteur demandant l'autorisation
+ * @param array $opt Options de cette autorisation
+ * @return bool true s'il a le droit, false sinon
*/
function autoriser_joindredocument_dist($faire, $type, $id, $qui, $opt){
include_spip('inc/config');
@@ -100,15 +135,17 @@ function autoriser_joindredocument_dist($faire, $type, $id, $qui, $opt){
/**
+ * Autorisation de modifier un document
+ *
* On ne peut modifier un document que s'il n'est pas lie a un objet qu'on n'a pas le droit d'editer
*
* @staticvar <type> $m
- * @param <type> $faire
- * @param <type> $type
- * @param <type> $id
- * @param <type> $qui
- * @param <type> $opt
- * @return <type>
+ * @param string $faire Action demandée
+ * @param string $type Type d'objet sur lequel appliquer l'action
+ * @param int $id Identifiant de l'objet
+ * @param array $qui Description de l'auteur demandant l'autorisation
+ * @param array $opt Options de cette autorisation
+ * @return bool true s'il a le droit, false sinon
*/
function autoriser_document_modifier_dist($faire, $type, $id, $qui, $opt){
static $m = array();
@@ -148,15 +185,17 @@ function autoriser_document_modifier_dist($faire, $type, $id, $qui, $opt){
/**
+ * Autorisation de supprimer un document
+ *
* On ne peut supprimer un document que s'il n'est lie a aucun objet
* ET qu'on a le droit de le modifier !
*
- * @param <type> $faire
- * @param <type> $type
- * @param <type> $id
- * @param <type> $qui
- * @param <type> $opt
- * @return <type>
+ * @param string $faire Action demandée
+ * @param string $type Type d'objet sur lequel appliquer l'action
+ * @param int $id Identifiant de l'objet
+ * @param array $qui Description de l'auteur demandant l'autorisation
+ * @param array $opt Options de cette autorisation
+ * @return bool true s'il a le droit, false sinon
*/
function autoriser_document_supprimer_dist($faire, $type, $id, $qui, $opt){
if (!intval($id)
@@ -183,15 +222,26 @@ function autoriser_document_supprimer_dist($faire, $type, $id, $qui, $opt){
}
-//
-// Peut-on voir un document dans _DIR_IMG ?
-// Tout le monde (y compris les visiteurs non enregistres), puisque par
-// defaut ce repertoire n'est pas protege ; si une extension comme
-// acces_restreint a positionne creer_htaccess, on regarde
-// si le document est lie a un element publie
-// (TODO: a revoir car c'est dommage de sortir de l'API true/false)
-//
-// http://doc.spip.org/@autoriser_document_voir_dist
+/**
+ * Autorisation de voir un document
+ *
+ * Peut-on voir un document dans _DIR_IMG ?
+ *
+ * Tout le monde (y compris les visiteurs non enregistrés), puisque par
+ * défaut ce repertoire n'est pas protégé ; si une extension comme
+ * acces_restreint a positionné creer_htaccess, on regarde
+ * si le document est lié à un élément publié.
+ *
+ * @todo
+ * À revoir car c'est dommage de sortir de l'API true/false
+ *
+ * @param string $faire Action demandée
+ * @param string $type Type d'objet sur lequel appliquer l'action
+ * @param int $id Identifiant de l'objet
+ * @param array $qui Description de l'auteur demandant l'autorisation
+ * @param array $opt Options de cette autorisation
+ * @return bool true s'il a le droit, false sinon
+**/
function autoriser_document_voir_dist($faire, $type, $id, $qui, $opt) {
if (!isset($GLOBALS['meta']["creer_htaccess"])
@@ -219,26 +269,35 @@ function autoriser_document_voir_dist($faire, $type, $id, $qui, $opt) {
/**
- * Auto-association de documents a du contenu editorial qui le reference
- * par defaut true pour tous les objets
+ * Autorisation d'auto-association de documents à du contenu editorial qui le référence
+ *
+ * Par defaut true pour tous les objets
+ *
+ * @param string $faire Action demandée
+ * @param string $type Type d'objet sur lequel appliquer l'action
+ * @param int $id Identifiant de l'objet
+ * @param array $qui Description de l'auteur demandant l'autorisation
+ * @param array $opt Options de cette autorisation
+ * @return bool true s'il a le droit, false sinon
*/
-function autoriser_autoassocierdocument_dist($faire, $type, $id, $qui, $opts) {
+function autoriser_autoassocierdocument_dist($faire, $type, $id, $qui, $opt) {
return true;
}
/**
- * Autoriser a nettoyer les orphelins de la base des documents
- * reserve aux admins complets
+ * Autoriser à nettoyer les orphelins de la base des documents
*
- * @param $faire
- * @param $type
- * @param $id
- * @param $qui
- * @param $opt
- * @return bool
+ * Réservé aux admins complets.
+ *
+ * @param string $faire Action demandée
+ * @param string $type Type d'objet sur lequel appliquer l'action
+ * @param int $id Identifiant de l'objet
+ * @param array $qui Description de l'auteur demandant l'autorisation
+ * @param array $opt Options de cette autorisation
+ * @return bool true s'il a le droit, false sinon
*/
function autoriser_orphelins_supprimer_dist($faire, $type, $id, $qui, $opt){
if ($qui['statut'] == '0minirezo'
AND !$qui['restreint'])
return true;
-}
\ No newline at end of file
+}
--
GitLab