Y a-t-il un moyen d'écrire des commentaires "standard" dans un maquillage pour les nourrir ultérieurement vers un programme de type DOXYGEN afin de produire une documentation agréable (HTML ou Man par exemple)? J'aimerais avoir un aperçu clair de mes principales cibles quelque part, mais rien de trop fantaisie.
6 Réponses :
Une belle touche est de fournir une citation de la cible qui imprime un résumé des objectifs et des options. Du noyau Linux Cela pourrait être un peu de travail pour maintenir la documentation de cette façon, mais je trouve qu'il sépare bien ce qui est destiné aux "utilisateurs "Versus ce qui est destiné aux personnes qui maintiennent le makefile : Makefile elle-même (commentaires en ligne).
Peut-être que je ne suis pas assez patient mais je doute qu'il y ait autre chose à part ce que vous avez mentionné. Merci beaucoup !!
Si vous souhaitez une sorte de choses automatisées, jetez un coup d'œil à make-help .
auto-documentant des maquillages (John Graham-Cumming, 2005) Vous permet d'écrire l'aide aux côtés de chaque règle. Il s'agit d'une solution légère et très importante qui fonctionne au moins avec GNU Gake.
Voici mon Version légèrement modifiée (Section de DEF-Help aide à organiser des listes longues de règles).
J'ai fait ma propre solution à l'aide d'un court script Perl qui formate l'aide comme d'autres outils GNU: qui donne ceci:
Un peu d'amélioration du bit help_fun: remplacer si / ^ (\ w +) \ s *: avec if / ^ ([\ w -_] +) \ s *: Afin de permettre des cibles du type "cible" ou "that_target" aussi.
Ce qui suit est une solution plus simple qui ne nécessite pas de définition de fonctions utilisateur ou d'agréger le texte de l'aide des règles qu'ils documentent.
----------------------------------------------------------------------
This is a help comment. The purpose of this Makefile is to demonstrate
a simple help mechanism that uses comments defined alongside the rules
they describe without the need of additional help files or echoing of
descriptions. Help comments are displayed in the order defined within
the Makefile.
----------------------------------------------------------------------
help: Show this help.
build: Build something.
install: Install something.
deploy: Deploy something.
format: Help comments are display with their leading whitespace. For
example, all comments in this snippet are aligned with spaces.
J'ai écrit le bibliothèque makehelp exactement à cette fin. Cela vous permet d'écrire les documents de règle au-dessus de chaque règle. Très facile à utiliser.
Je trouve qu'il est différent des autres makefiles auto-documentant ici car il n'a pas de répétitivité et permet aux documents multilignes et aux règles privées.
dans un maquillage tel que: va sortir: 