Changeset 92939 in spip-zone


Ignore:
Timestamp:
Nov 15, 2015, 9:16:40 AM (4 years ago)
Author:
eric@…
Message:

Phpdoc de l'API de taxonomie et renommage.

Location:
_plugins_/taxonomie/trunk
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • _plugins_/taxonomie/trunk/prive/objets/contenu/taxon.html

    r92851 r92939  
    3333<//B_ascendance>
    3434
    35 [(#SET{sources, [(#ID_TAXON|taxonomie_crediter{#SOURCES})]})]
     35[(#SET{sources, [(#ID_TAXON|taxonomie_informer_credits{#SOURCES})]})]
    3636<B_sources>
    3737<div class="champ contenu_ps">
  • _plugins_/taxonomie/trunk/taxonomie_fonctions.php

    r92841 r92939  
    99
    1010/**
    11  * Chargement de tous les taxons d'un règne donné, du règne lui-même aux taxons de genre au maximum.
     11 * Charge tous les taxons d'un règne donné, du règne lui-même aux taxons de genre au maximum.
    1212 * La fonction permet aussi de choisir un rang taxonomique feuille différent du genre.
    13  * Les nom communs anglais et français peuvent aussi être chargés en complément mais
     13 * Les nom communs anglais, français ou espagnols peuvent aussi être chargés en complément mais
    1414 * ne couvrent pas l'ensemble des taxons.
    1515 *
    1616 * @api
    1717 * @filtre
     18 * @uses taxonomie_regne_existe()
     19 * @uses preserver_taxons_edites()
     20 * @uses taxonomie_vider_regne()
     21 * @uses itis_read_hierarchy()
     22 * @uses itis_spipcode2language()
     23 * @uses itis_read_vernaculars()
    1824 *
    1925 * @param string        $regne
    20  *              Nom scientifique du règne en lettres minuscules (animalia, plantae, fungi)
     26 *              Nom scientifique du règne en lettres minuscules : `animalia`, `plantae`, `fungi`.
    2127 * @param string        $rang
    2228 *              Rang taxonomique minimal jusqu'où charger le règne. Ce rang est fourni en anglais, en minuscules et
    23  *              correspond à : phylum, class, order, family, genus.
     29 *              correspond à : `phylum`, `class`, `order`, `family`, `genus`.
    2430 * @param array         $codes_langue
    2531 *              Tableau des codes (au sens SPIP) des langues à charger pour les noms communs des taxons.
    2632 *
    2733 * @return bool
    28  *              Retour true/false
     34 *              `true` si le chargement a réussi, `false` sinon
    2935 */
    3036function taxonomie_charger_regne($regne, $rang, $codes_langue=array()) {
     
    5056        if ($taxons) {
    5157                $meta_regne['compteur'] = count($taxons);
    52         $traductions = array();
     58                $traductions = array();
    5359                foreach ($codes_langue as $_code_langue) {
    5460                        $langue = itis_spipcode2language($_code_langue);
     
    6066                                        foreach ($noms as $_tsn => $_nom) {
    6167                                                if (array_key_exists($_tsn, $taxons)) {
    62                                 // On ajoute les traductions qui sont de la forme [xx]texte
    63                                 // On sauvegarde le tsn concerné afin de clore les traductions
    64                                 // avec les balises multi et d'optimiser ainsi les traitements
    65                                 // sachant qu'il y a très peu de traductions comparées aux taxons
     68                                                        // On ajoute les traductions qui sont de la forme [xx]texte
     69                                                        // On sauvegarde le tsn concerné afin de clore les traductions
     70                                                        // avec les balises multi et d'optimiser ainsi les traitements
     71                                                        // sachant qu'il y a très peu de traductions comparées aux taxons
    6672                                                        $taxons[$_tsn]['nom_commun'] .= $_nom;
    6773                                                        $nb_traductions += 1;
    68                                 $traductions[$_tsn] = $_tsn;
     74                                                        $traductions[$_tsn] = $_tsn;
    6975                                                }
    7076                                        }
     
    7480                }
    7581
    76         // Clore les traductions avec les balises multi
    77         if ($traductions) {
    78             foreach ($traductions as $_tsn) {
    79                 $taxons[$_tsn]['nom_commun'] =  '<multi>' . $taxons[$_tsn]['nom_commun'] . '</multi>';
    80             }
    81         }
     82                // Clore les traductions avec les balises multi
     83                if ($traductions) {
     84                        foreach ($traductions as $_tsn) {
     85                                $taxons[$_tsn]['nom_commun'] =  '<multi>' . $taxons[$_tsn]['nom_commun'] . '</multi>';
     86                        }
     87                }
    8288
    8389                // Réinjection des taxons modifiés manuellement
     
    115121
    116122/**
    117  * Suppression de tous les taxons d'un règne donné de la base de données.
     123 * Supprime tous les taxons d'un règne donné de la base de données.
    118124 * La meta concernant les informations de chargement du règne est aussi effacée.
    119  * Les modifications manuelles effectuées sur les taxons du règne sont perdues!
     125 * Les modifications manuelles effectuées sur les taxons du règne sont perdues, elles
     126 * doivent donc être préservées au préalable.
    120127 *
    121128 * @api
     
    123130 *
    124131 * @param string        $regne
    125  *              Nom scientifique du règne en lettres minuscules (animalia, plantae, fungi)
     132 *              Nom scientifique du règne en lettres minuscules : `animalia`, `plantae`, `fungi`.
    126133 *
    127134 * @return bool
    128  *              Retour true/false
     135 *              `true` si le vidage a réussi, `false` sinon
    129136 */
    130137function taxonomie_vider_regne($regne) {
     
    141148
    142149/**
    143  * Interrogation sur l'existence ou pas d'un règne en base de données.
    144  * La fonction scrute la table spip_taxons et non la meta propre au règne.
     150 * Retourne l'existence ou pas d'un règne en base de données.
     151 * La fonction scrute la table `spip_taxons` et non la meta propre au règne.
    145152 *
    146153 * @api
     
    148155 *
    149156 * @param string        $regne
    150  *              Nom scientifique du règne en lettres minuscules (animalia, plantae, fungi)
     157 *              Nom scientifique du règne en lettres minuscules : `animalia`, `plantae`, `fungi`.
    151158 * @param array         $meta_regne
    152159 *              Meta propre au règne, créée lors du chargement de celui-ci et retournée si le règne
    153  *              existe
     160 *              existe.
    154161 *
    155162 * @return bool
     163 *              `true` si le règne existe, `false` sinon.
    156164 */
    157165function taxonomie_regne_existe($regne, &$meta_regne) {
     
    172180
    173181/**
    174  * Liste dans un tableau les rangs taxonomiques supportés par le plugin, à savoir:
    175  * kingdom, phylum, class, order, family, genus et species.
    176  * Les règnes sont exprimés en anglais et écrits en lettres minuscules.
    177  * La fonction permet d'exclure de la liste les rangs extrêmes kingdom et specie et de choisir
    178  * entre le rang phylum et son synonyme division.
    179  *
    180  * @param bool $exclure_regne
    181  *              Demande d'exclusion du règne de la liste des rangs
    182  * @param bool $exclure_espece
    183  *              Demande d'exclusion de l'espèce de la liste des rangs
     182 * Liste dans un tableau les rangs taxonomiques supportés par le plugin, suivant certains critères.
     183 * Les règnes et les rangs sont exprimés en anglais et écrits en lettres minuscules.
     184 * La fonction permet d'exclure certains rangs de la liste.
     185 *
     186 * @api
     187 * @filtre
     188 *
    184189 * @param string        $regne
    185  *              Nom scientifque du règne pour lequel la liste des rangs est demandée.
    186  *              Cet argument permet de remplacer le rang phylum par division qui est son synonyme
    187  *              pour les règnes fongique et végétal
     190 *              Nom scientifique du règne pour lequel la liste des rangs est demandée.
     191 *              Cet argument permet de remplacer le rang `phylum` par `division` qui est son synonyme
     192 *              pour les règnes fongique et végétal.
     193 * @param array         $liste_base
     194 *              Liste de base contenant les rangs par défaut à renvoyer. Il existe deux listes de base, à savoir :
     195 *              - du règne au genre (`_TAXONOMIE_RANGS_PARENTS_ESPECE`)
     196 *              - de l'espèce à la sous-forme (`_TAXONOMIE_RANGS_ESPECE_ET_FILS`)
     197 * @param array         $exclusions
     198 *              Liste des rangs à exclure de la liste fournie dans l'argument `$liste_base`
    188199 *
    189200 * @return array
     201 *              Liste des rangs demandée.
    190202 */
    191203function taxonomie_lister_rangs($regne=_TAXONOMIE_REGNE_ANIMAL, $liste_base, $exclusions=array()) {
     
    206218
    207219/**
    208  * Fourniture de l'ascendance taxonomique d'un taxon donné.
    209  *
    210  * @api
    211  * @filtre
    212  *
    213  * @param int   $id_taxon
    214  *              Id du taxon pour lequel il faut fournir l'ascendance
    215  * @param int   $tsn_parent
     220 * Fournit l'ascendance taxonomique d'un taxon donné par consultation en base de données.
     221 *
     222 * @api
     223 * @filtre
     224 *
     225 * @param int           $id_taxon
     226 *              Id du taxon pour lequel il faut fournir l'ascendance.
     227 * @param int           $tsn_parent
    216228 *      TSN du parent correspondant au taxon id_taxon. Ce paramètre permet d'optimiser le traitement
    217  *              mais n'est pas obligatoire.
     229 *              mais n'est pas obligatoire. Si il n'est pas connu lors de l'appel il faut passer `null`.
     230 * @param string        $ordre
     231 *              Classement de la liste des taxons : `descendant`(défaut) ou `ascendant`.
    218232 *
    219233 * @return array
     234 *              Liste des taxons ascendants. Chaque taxon est un tableau associatif contenant les informations
     235 *              suivantes : `id_taxon`, `tsn_parent`, `nom_scientifique`, `nom_commun`, `rang`.
    220236 */
    221237function taxonomie_informer_ascendance($id_taxon, $tsn_parent=null, $ordre='descendant') {
     
    248264
    249265/**
    250  * Fourniture des sources d'information ayant permis de compléter le taxon.
    251  * La référence ITIS n'est pas répétée dans le champ sources de chaque taxon car elle est
    252  * à la base de chaque règne. Elle est donc insérée par la fonction elle-même.
    253  *
    254  * @api
    255  * @filtre
     266 * Fournit les phrases de crédits des sources d'information ayant permis de compléter le taxon.
     267 * La référence ITIS n'est pas répétée dans le champ `sources` de chaque taxon car elle est
     268 * à la base de chaque règne. Elle est donc insérée par la fonction.
     269 *
     270 * @api
     271 * @filtre
     272 * @uses ${service}_credit, fonction de formatage des crédits propre à chaque service
    256273 *
    257274 * @param int           $id_taxon
    258  *              Id du taxon pour lequel il faut fournir l'ascendance
     275 *              Id du taxon pour lequel il faut fournir les crédits
    259276 * @param string        $sources_specifiques
    260  *              Tableau sérialisé des identifiants des sources possibles autres qu'ITIS (CINFO, WIKIPEDIA...).
     277 *              Tableau sérialisé des sources possibles autres qu'ITIS (CINFO, WIKIPEDIA...) telles qu'enregistrées
     278 *              en base de données dans le champ `sources`.
    261279 *              Ce paramètre permet d'optimiser le traitement mais n'est pas obligatoire.
    262280 *
    263281 * @return array
    264  */
    265 function taxonomie_crediter($id_taxon, $sources_specifiques=null) {
     282 *              Tableau des phrases de crédits indexées par source.
     283 */
     284function taxonomie_informer_credits($id_taxon, $sources_specifiques=null) {
    266285        $sources = array();
    267286
     
    279298
    280299        // Puis on construit la liste des sources pour l'affichage
    281         foreach ($liste_sources as $_source => $_infos_source) {
    282                 include_spip("services/${_source}/${_source}_api");
    283                 if (function_exists($citer = "${_source}_credit")) {
    284                         $sources[$_source] = $citer($id_taxon, $_infos_source);
     300        foreach ($liste_sources as $_service => $_infos_source) {
     301                include_spip("services/${_service}/${_service}_api");
     302                if (function_exists($citer = "${_service}_credit")) {
     303                        $sources[$_service] = $citer($id_taxon, $_infos_source);
    285304                }
    286305        }
Note: See TracChangeset for help on using the changeset viewer.