Lowlight.fr

L'humanité ne peut rien obtenir sans donner quelque chose en retour.

Fullmetal Alchemist
Hiromu Arakawa

Pourquoi documenter ?

Coder, c'est aussi **documenter**. Un développeur a beau faire le programme le plus performant et innovant du monde, si personne ne sait l'utiliser, il ne sert à rien.

La race humaine a pu évoluer grâce à nos ancêtres qui ont su nous faire parvenir tout le savoir qu'ils ont pu accumuler au fil des siècles. Documenter ses travaux permet à d'autres personnes d'y contribuer, de le corriger et de l'améliorer.

C'est dans cette optique que j'ai réalisé **Spotlight** °(disponible sur **GitHub**)°, un template pour **JSDoc 3** (outil de documentation basé sur la syntaxe de la **JavaDoc**). Si vous ne savez pas ce qu'est la **JavaDoc**, vous pouvez voir un exemple en cliquant ci-dessous.

Exemple de JavaDoc

    class LapisPhilosophorum {
        /**
         * Pierre philosophale (voir sur [Wikipédia]{@link https://fr.wikipedia.org/wiki/Pierre_philosophale}).
         * Permet de transmuter des instances de métaux imparfait en métaux parfait, et de soigner ou rajeurnir un être humain.
         * @param {MagnumOpus} opus - Instance du Magnum Opus ayant permis de réaliser la pierre philoshophale
         * @see MagnumOpus
         * @author Nicolas Flamel
         */
            constructor(opus) {
                /**
                 * Indique si le Magnum Opus a été achevé ou non.
                 * @type {Boolean}
                 */
                    this.completed = opus.completed
            }

        /**
         * Effectue la transmutation d'un métal imparfait en métal parfait.
         * Le résultat dépend de l'état d'avancement du Magnum Opus.
         * @param {Metal} metal - Métal imparfait à transmuter (mercure, plomb ou étain) en métal parfait
         * @return {Gold|Silver} Métal parfait (or ou argent)
         * @throws {Error} Le métal passé en argument est déjà parfait et ne peut être transmuté de nouveau
         */
            transmute(metal) {
                if (!metal.perfect) {
                    metal.destroy()
                    return this.completed ? new Gold() : new Silver()
                }
                throw new Error("Metal is already perfect and cannot be transmuted again")
            }

        /**
         * Soigne un être humain de ses différentes maladies.
         * @param {Human} human - Etre humain à soigner
         */
            heal(human) {
                human.diseases.clear()
            }

        /**
         * Rajeunit un être humain d'un certain nombre d'années.
         * @param {Human} human - Etre humain à rajeunir
         * @param {Number} [years=10] - Nombre d'années de rajeunissement
         */
            rejuvenate(human, years = 10) {
                human.age = Math.max(20, human.age - years)
            }
    }
                
Voici un aperçu d'un site généré avec le template **Spotlight**, °(qui est celui que j'utilise pour documenter tous mes projets)°.