Open Time

En train de revoir un gros fichier, inc/public/class.dc.template.php, qui définit l’essentiel des balises template disponible dans Dotclear.

J’y ai trouvé de la doc au pseudo-format dtd qui décrit les attributs possibles d’icelles, doc qui servait un temps à générer automatiquement la documentation associée sur le site Dotclear.

Exemple :

    /*dtd
    <!ELEMENT tpl:BlogUpdateDate - O -- Blog last update date -->
    <!ATTLIST tpl:BlogUpdateDate
    format    CDATA    #IMPLIED    -- date format (encoded in dc:str by default if iso8601 or rfc822 not specified)
    iso8601    CDATA    #IMPLIED    -- if set, tells that date format is ISO 8601
    rfc822    CDATA    #IMPLIED    -- if set, tells that date format is RFC 822
    >
     */
    public function BlogUpdateDate($attr)
    {
        …
    }

Cette documentation, sur le site Dotclear, n’a en fait pas été mise à jour depuis 2013 ; je suppose qu’à l’époque il y avait encore un outil pour la générer depuis le code source, mais je n’ai pas réussi à mettre la main dessus, ce qui n’est pas grave en soi puisqu’en fait cette documentation n’est pas accessible facilement depuis l’index de la documentation Dotclear.

Il en existe une autre, mise à jour au fur et à mesure, qui est disponible depuis cette page. Page accessible facilement depuis l’index de la documentation des ressources.

Du coup, deux questions :

1. Est-ce qu’il ne faudrait pas virer la « vieille » doc des balises qui date de 2013, balises qui ont un peu bougé (voire beaucoup) depuis pour certaines ?

2. Est-ce qu’il est utile que je documente dans le code les attributs d’icelles (voir un exemple ci-dessous) — dit autrement est-ce que ça ne fait pas double emploi¹ ?

   /**
     * tpl:BlogFeedURL [attributes] : Display blog feed URL (tpl value)
     *
     * attributes:
     *
     *      type            (rss2|atom)     Feed type, default to "atom"
     *      any filters     See self::getFilters()
     *
     * @param      ArrayObject    $attr     The attributes
     *
     * @return     string
     */
    public function BlogFeedURL(ArrayObject $attr): string
    {
        …
    }