Fond de tiroir #1 ~ Générateur de doc javascript monofichier
jeudi 1 juin 2017 à 21:30Si vous êtes un développeur dans l’âme, vous avez déjà eu à faire à cette problématique de la petite idée de projet que vous avez codé en une aprèm puis que vous n’avez jamais eu l’envie le temps de retoucher.
Plus le temps passe et plus le nombre d’idées qui végètent sans but dans votre placard à projet s’accumulent… A la lumière de ce constat, j’ai décidé d’ouvrir une petite rubrique pour partager mes fonds de tiroirs, plusieurs n’en sont qu’aux balbutiements, aussi je les partage sur ce blog avec quelques explications au cas ou quelqu’un souhaiterais les ré-exploiter.
Mon fond de tiroir du jour est un petit fichier php unique permettant de générer une doc minimaliste au format HTML à partir d’un fichier javascript.
Concrètement le PHP parse les commentaires au dessus de chaque fonction javascript et génère une page unique de consultation formatée (nom de la fonction, paramètres, descriptif en commentaire…).
La mise en forme reste volontairement simpliste de manière a pouvoir faire un copier coller sur word ou autres éditeurs répandus n’acceptant pas le javascript/css poussé.
Points forts :
- Simple d’utilisation (simplement deux variables à configurer)
- Template html de sortie facile a modifier
- Mono fichier
- Pas de prérequis autre que PHP
- Pas besoin d’avoir respecté les normes de commentaires de documentation
Points faibles:
- Codé avec les pied
- Doc générée ultra minimaliste
- non conforme aux standard de commentaires de docs
- Créé a la base pour une feuille de plugins jquery donc pas forcement utile/a adapter ailleurs
- Les méthodes statiques sont uniquement définie pour les plugins jquery
Le fichier PHP est ici pour ceux que ça intéresse :
Télécharger le bousin