autogsdoc - Générateur de documentation de l'API GNUstep et convertisseur XML->HTML
autogsdoc [-Files filename] [-GenerateHtml YES|no] [-Clean yes|NO] [-CleanTemplates yes|NO] [-IgnoreDependencies yes|NO] [-MakeDependencies yes|NO] [-ShowDependencies yes|NO] [-HeaderDirectory path] [-DocumentationDirectory path] [-Declared location] [-Project title] [-Standards yes|NO] [-DocumentAllInstanceVariables yes|NO] [-DocumentInstanceVariables YES|no] [-InstanceVariablesAtEnd yes|NO] [-ConstantsTemplate filename] [-FunctionsTemplate filename] [-MacrosTemplate filename] [-TypedefsTemplate filename] [-VariablesTemplate filename] [-SystemProjects string] [-LocalProjects string] [-Projects dictString] [-Verbose yes|NO] [-Warn yes|NO] [-WordMap dictString] [files]
L'outil autogsdoc est un utilitaire de ligne de commande qui aide les développeurs à produire une documentation de référence pour les API GNUstep. Il permet également aux développeurs d'écrire et de maintenir d'autres documentations en XML et de les convertir en HTML. En détail, autogsdoc va :
Extrayez des commentaires spéciaux décrivant les interfaces publiques des classes, catégories, protocoles, fonctions et macros du code source Objective C (fichiers d'en-tête et éventuellement fichiers source) dans des fichiers XML GSDoc.
Convertissez les fichiers XML GSDoc, qu'ils soient générés à partir du code source ou écrits manuellement par les développeurs, en HTML.
Construisez des index basés sur des ensembles de fichiers XML GSDoc et convertissez-les également en HTML.
L'utilisation la plus courante consiste à exécuter la commande avec un ou plusieurs noms de fichiers d'en-tête comme arguments ... l'outil analysera automatiquement les fichiers source correspondants dans le même répertoire que les en-têtes (ou le répertoire courant, ou le répertoire spécifié à l'aide de DocumentationDirectory par défaut) et produire des fichiers GSDoc et HTML en sortie. Pour de meilleurs résultats, ce mode doit être exécuté à partir du répertoire contenant les fichiers source. (Notez que puisque C est un sous-ensemble d'Objective C, cet outil peut fonctionner pour documenter des fonctions et d'autres structures C dans une source C ordinaire.)
Les fichiers GSDoc peuvent également être donnés directement en complément ou seuls, et seront convertis en HTML. Consultez la documentation HTML GSDoc ou la page de manuel gsdoc(7) pour plus d'informations sur le format GSDoc.
Enfin, les fichiers HTML peuvent être donnés sur la ligne de commande. Les références croisées à d'autres parties de la documentation du code qui s'y trouvent seront réécrites en fonction de ce qui se trouve actuellement dans le projet.
L'analyseur de code source produira automatiquement des documents GSDoc listant les méthodes dans les classes trouvées dans les fichiers source, et il inclura le texte des commentaires spécialement formatés des fichiers source.
Tout commentaire commençant par une barre oblique et deux astérisques plutôt qu'une barre oblique commune et un seul astérisque, est considéré comme un balisage GSDoc, à utiliser comme description de la classe ou de la méthode qui le suit. Ce texte de commentaire est reformaté puis inséré dans la sortie.
Lorsque plusieurs commentaires sont associés à un même élément, ils sont reliés entre eux par un saut de ligne (
) si nécessaire.L'outil peut facilement être utilisé pour documenter des programmes ainsi que des bibliothèques, simplement en lui donnant le nom du fichier source contenant la fonction main() du programme - il prend les commentaires spéciaux de cette fonction et les gère spécialement, en les insérant comme une section à la fin du premier chapitre du document (il crée le premier chapitre si nécessaire).
Les options sont décrites dans la section Arguments et valeurs par défaut ci-dessous.
Il existe certains cas où un traitement supplémentaire spécial est effectué, principalement dans le premier commentaire trouvé dans le fichier source, à partir duquel divers morceaux de balisage GSDoc peuvent être extraits et placés dans des emplacements appropriés dans le document de sortie -
Dans toute ligne où AutogsdocSource : est trouvé, le reste de la ligne est considéré comme un nom de fichier source à utiliser au lieu de supposer que chaque fichier .h traité utilise un fichier .m du même nom. Vous pouvez fournir plusieurs lignes AutogsdocSource : où un fichier d'en-tête déclare des éléments qui sont définis dans plusieurs fichiers source. Si un nom de fichier est absolu, il est utilisé tel qu'il est fourni. Si, d'autre part, il s'agit d'un chemin relatif, le logiciel recherche d'abord le fichier source par rapport à l'emplacement du fichier d'en-tête, et s'il ne s'y trouve pas, par rapport au répertoire actuel dans lequel autogsdoc s'exécute, et enfin par rapport à le répertoire spécifié par la valeur par défaut de DocumentationDirectory.
Un résumé du contenu du document ... placé dans l'en-tête de la sortie GSDoc.
Une description de l'auteur du code - peut être répétée pour gérer le cas où un document a plusieurs auteurs. Placé dans la tête de la sortie GSDoc. Pour faciliter la lisibilité de la source, un traitement supplémentaire spécial est effectué en fonction de l'auteur du document - Toute ligne du formulaire
nom
nom
nom' ou
name' sera reconnu et converti en un élément author, contenant éventuellement un élément email.
Placé dans la sortie GSDoc juste avant la fin du corps du document - destiné à être utilisé pour les annexes, l'index, etc.
Placé immédiatement avant toute documentation de classe générée ... destiné à être utilisé pour fournir une description globale du fonctionnement du code documenté. Toute documentation relative à la fonction main() d'un programme est insérée sous forme de section à la fin de ce chapitre.
Copyright du contenu du document ... placé dans l'en-tête de la sortie GSDoc. Pour aider à la lisibilité de la source, un traitement supplémentaire spécial est effectué - Toute ligne de la forme 'Texte de copyright (C)' sera reconnue et convertie en un élément copy.
Date de la révision du document ... placée dans l'en-tête de la sortie GSDoc. Si cela est omis, l'outil essaiera de construire une valeur à partir de la balise RCS Date (si disponible).
Inséré dans le document au début du corps ... destiné à fournir des pages d'introduction ou de sommaire, etc.
Titre du document ... placé dans l'en-tête de la sortie GSDoc. Si cela est omis, l'outil générera son propre titre (probablement médiocre) - vous devez donc inclure ce balisage manuellement.
Identifiant de version du document ... placé dans l'en-tête de la sortie GSDoc. Si cela est omis, l'outil essaiera de construire une valeur à partir de la balise RCS Revision (si disponible).
NB Le balisage qui vient d'être décrit peut être utilisé dans la documentation de classe, de catégorie ou de protocole ... si c'est le cas, il est extrait et enveloppé autour du reste de la documentation de la classe en tant que chapitre de la classe. Le reste de la documentation de la classe est normalement inséré à la fin du chapitre, mais peut à la place être remplacé par le pseudo-élément
Dans les commentaires utilisés pour fournir du texte pour une description de méthode, le balisage suivant est supprimé du texte et traité spécialement -
La méthode est marquée comme étant l'initialiseur désigné pour la classe.
La méthode est marquée comme étant celle que les sous-classes doivent remplacer (par exemple, une méthode abstraite).
La méthode est marquée comme étant celle que les sous-classes ne doivent PAS remplacer.
Le balisage est supprimé de la description et placé après dans la sortie GSDoc - de sorte que la méthode est décrite comme conforme (ou non conforme) aux normes spécifiées.
Généralement, le texte des commentaires est reformaté pour le normaliser et le mettre en retrait ... le reformatage n'est pas effectué sur aucun texte à l'intérieur d'un élément
Certaines constantes bien connues telles que YES, NO et nil sont incluses dans le balisage ... .
Les noms des arguments de méthode dans les descriptions de méthode sont inclus dans le balisage ... .
Les noms de méthodes (commençant par un plus ou un moins) sont inclus dans le balisage
Les spécificateurs de méthode incluant les noms de classe (commençant et se terminant par des crochets) sont inclus dans le balisage
Les noms de fonction (se terminant par '()') autres que 'main()' sont inclus dans le balisage
L'outil accepte certaines valeurs par défaut de l'utilisateur (qui peuvent bien sûr être fournies en tant qu'arguments de ligne de commande en ajoutant '-' avant le nom par défaut et en donnant la valeur après, comme dans -Clean YES) :
Si cette valeur booléenne est définie sur OUI, alors plutôt que de générer de la documentation, l'outil supprime tous les fichiers GSDoc générés dans le projet, et tous les fichiers html générés à partir d'eux (ainsi que ceux qui seraient générés à partir des fichiers GSDoc répertoriés explicitement), et supprime finalement le fichier d'index du projet. La seule exception à cela est que les modèles de fichiers GSDoc (c'est-à-dire ceux spécifiés à l'aide des arguments "-ConstantsTemplate ...", "-FunctionsTemplate ...", etc.) ne sont pas supprimés à moins que l'indicateur CleanTemplates ne soit défini.
Cet indicateur spécifie si les fichiers modèles GSDoc doivent être supprimés avec d'autres fichiers lorsque l'option Nettoyer est spécifiée. Par défaut, ils ne doivent pas être supprimés ... car ces modèles peuvent avoir été produits manuellement et n'avoir que des données insérées dedans.
Spécifiez le nom d'un modèle de document dans lequel la documentation sur les constantes doit être insérée à partir de tous les fichiers du projet. Ceci est utile si les constantes du code source sont dispersées dans de nombreux fichiers et que vous devez les regrouper en un seul endroit. Vous êtes responsable de vous assurer que le modèle de document de base (dans lequel la documentation des constantes individuelles est insérée) contient toutes les autres informations souhaitées, mais par souci de commodité, autogsdoc générera un modèle simple (que vous pourrez ensuite modifier) pour vous si le fichier ne n'existe pas. L'insertion a lieu juste avant l'élément back (ou s'il n'existe pas, juste avant la fin de l'élément body) dans le modèle.
Spécifiez où les en-têtes doivent être documentés comme étant trouvés. Le nom réel produit dans la documentation est formé en ajoutant le dernier composant du nom du fichier d'en-tête à la valeur de cette valeur par défaut. Si cette valeur par défaut n'est pas spécifiée, le nom complet du fichier d'en-tête (tel qu'il est fourni sur la ligne de commande), suivi de la valeur par défaut HeaderDirectory, est utilisé. Une utilisation typique de ceci pourrait être '"-Declared Foundation"' lors de la génération de documentation pour la bibliothèque de base GNUstep. Cela se traduirait par la documentation indiquant que NSString est déclaré dans 'Foundation/NSString.h'
Cet indicateur vous permet de générer de la documentation pour toutes les variables d'instance. Normalement, seuls ceux explicitement déclarés « publics » ou « protégés » seront documentés.
Cet indicateur vous permet de désactiver complètement la documentation des variables d'instance. Normalement, les variables d'instance explicitement déclarées 'publiques' ou 'protégées' seront documentées.
Cet indicateur, s'il est défini, indique au générateur HTML de placer la documentation de la variable d'instance à la fin de la classe, au lieu du début. Ceci est utile si vous utilisez beaucoup de variables d'instance protégées qui n'auront qu'un intérêt secondaire pour les utilisateurs généraux de la classe.
Peut être utilisé pour spécifier le répertoire dans lequel la documentation générée doit être placée. S'il n'est pas défini, la sortie est placée dans le répertoire courant. Ce répertoire est également utilisé en dernier recours pour localiser les fichiers source (pas les en-têtes), et plus important encore, il est utilisé comme premier et unique recours pour localiser tous les fichiers .gsdoc transmis sur le ligne de commande. Toute information de chemin donnée pour ces fichiers est supprimée et ils sont recherchés dans 'DocumentationDirectory' (même s'ils n'ont pas été générés automatiquement).
Spécifie le nom d'un fichier contenant une liste de noms de fichiers sous la forme d'un tableau de liste de propriétés au format (nom1,nom2,...). S'il est présent, les noms de fichiers dans la liste d'arguments du programme sont ignorés et les noms de ce fichier sont utilisés comme liste de noms à traiter.
Spécifiez le nom d'un modèle de document dans lequel la documentation sur les fonctions doit être insérée à partir de tous les fichiers du projet. Ceci est utile si le code source de la fonction est dispersé dans de nombreux fichiers et que vous devez le regrouper en un seul endroit. Vous êtes responsable de vous assurer que le modèle de document de base (dans lequel la documentation de la fonction individuelle est insérée) contient toutes les autres informations souhaitées, mais par souci de commodité, autogsdoc générera un modèle simple (que vous pourrez ensuite modifier) pour vous si le fichier ne n'existe pas. L'insertion a lieu juste avant l'élément back (ou s'il n'existe pas, juste avant la fin de l'élément body) dans le modèle.
Peut être utilisé pour spécifier si la sortie HTML doit être générée. La valeur par défaut est OUI.
Peut être utilisé pour spécifier le répertoire dans lequel rechercher les fichiers d'en-tête. Lorsqu'elle est fournie, cette valeur est ajoutée aux noms d'en-tête relatifs, sinon les noms d'en-tête relatifs sont interprétés par rapport au répertoire courant. Les fichiers d'en-tête spécifiés comme chemins absolus ne sont pas influencés par cette valeur par défaut.
Une valeur booléenne qui peut être utilisée pour spécifier que le programme doit ignorer les heures de modification des fichiers et régénérer les fichiers de toute façon. Fourni pour être utilisé en conjonction avec le système 'make', qui est censé gérer lui-même la vérification des dépendances.
Cette valeur est utilisée pour contrôler l'inclusion automatique des projets externes locaux dans le système d'indexation pour la génération de références croisées dans la sortie du document final. S'il est défini sur 'Aucun', aucune référence de projet local n'est effectuée, sinon, le répertoire de documentation GNUstep 'Local' est recherché de manière récursive pour les fichiers avec une extension '.igsdoc', et les informations d'indexation de ces fichiers sont utilisées. La valeur de cette chaîne est également utilisée pour générer les noms de fichiers dans la référence croisée ... si c'est une chaîne vide, le chemin à utiliser est supposé être un fichier dans le même répertoire où le fichier igsdoc a été trouvé, sinon il est utilisé comme préfixe du nom dans l'index. NB. Les projets locaux portant le même nom que le projet en cours de documentation ne seront pas inclus par ce mécanisme. Si vous souhaitez inclure de tels projets, vous devez le faire explicitement en utilisant -Projects ...
Spécifiez le nom d'un modèle de document dans lequel la documentation sur les macros doit être insérée à partir de tous les fichiers du projet. Ceci est utile si le code de macro est dispersé dans de nombreux fichiers et que vous devez le regrouper en un seul endroit. Vous êtes responsable de vous assurer que le modèle de document de base (dans lequel la documentation de la macro individuelle est insérée) contient toutes les autres informations souhaitées, mais pour plus de commodité, autogsdoc générera un modèle simple (que vous pourrez ensuite modifier) pour vous si le fichier ne n'existe pas. L'insertion a lieu juste avant l'élément back (ou s'il n'existe pas, juste avant la fin de l'élément body) dans le modèle.
Un nom de fichier à utiliser pour afficher les informations de dépendance pour make. Cela prendra la forme d'une liste de tous les fichiers d'en-tête et source connus pour le projet en tant que dépendances du nom du projet (voir 'Projet').
Peut être utilisé pour spécifier le nom de ce projet ... détermine le nom du fichier de référence d'index produit dans le cadre de la documentation pour fournir des informations permettant à d'autres projets de se référer aux éléments de ce projet.
Cette valeur peut être fournie sous la forme d'un dictionnaire contenant les chemins d'accès aux fichiers d'index/de référence igsdoc utilisés par des projets externes, ainsi que des valeurs à utiliser pour mapper les noms de fichiers trouvés dans les index. Par exemple, si un fichier d'index de projet (igsdoc) indique que la classe 'Foo' se trouve dans le fichier 'Foo' et que le chemin associé à cet index de projet est '/usr/share/doc/proj', le code html généré la sortie peut faire référence à la classe comme étant dans '/usr/share/doc/prj/Foo.html' . Notez qu'un dictionnaire peut être donné sur la ligne de commande en utilisant le format standard PropertyList (et non le format XML d'OS X), en utilisant des points-virgules comme séparateurs de ligne et en l'entourant de guillemets simples.
Une valeur booléenne qui peut être utilisée pour spécifier que le programme doit consigner quels fichiers sont régénérés en raison de leurs dépendances sur d'autres fichiers.
Une valeur booléenne utilisée pour spécifier si le programme doit insérer des informations sur la conformité aux normes dans la documentation. Cela ne devrait être utilisé que lors de la documentation des bibliothèques et des outils GNUstep eux-mêmes, car cela suppose que le code documenté fait partie de GNUstep et est éventuellement conforme au standard OpenStep ou implémente des méthodes compatibles avec MacOS-X.
Cette valeur est utilisée pour contrôler l'inclusion automatique des projets externes au système dans le système d'indexation pour la génération de références croisées dans la sortie finale du document. S'il est défini sur 'Aucun', aucune référence de projet système n'est effectuée, sinon, le répertoire de documentation 'System' GNUstep est recherché de manière récursive pour les fichiers avec une extension '.igsdoc', et les informations d'indexation de ces fichiers sont utilisées. La valeur de cette chaîne est également utilisée pour générer les noms de fichiers dans la référence croisée ... si c'est une chaîne vide, le chemin à utiliser est supposé être un fichier dans le même répertoire où le fichier igsdoc a été trouvé, sinon il est utilisé comme préfixe du nom dans l'index. NB. Les projets système portant le même nom que le projet en cours de documentation ne seront pas inclus par ce mécanisme. Si vous souhaitez inclure de tels projets, vous devez le faire explicitement en utilisant -Projects ...
Spécifiez le nom d'un modèle de document dans lequel la documentation sur les typedefs doit être insérée à partir de tous les fichiers du projet. Ceci est utile si le code source typedef est dispersé dans de nombreux fichiers et que vous devez le regrouper en un seul endroit. Vous êtes responsable de vous assurer que le modèle de document de base (dans lequel la documentation typedef individuelle est insérée) contient toutes les autres informations souhaitées, mais pour plus de commodité, autogsdoc générera un modèle simple (que vous pourrez ensuite modifier) pour vous si le fichier ne n'existe pas. L'insertion a lieu juste avant l'élément back (ou s'il n'existe pas, juste avant la fin de l'élément body) dans le modèle.
Une chaîne utilisée pour fournir le nom à utiliser dans le lien 'up' des documents GSDoc générés. Il doit normalement s'agir du nom d'un fichier contenant un index du contenu d'un projet. S'il est manquant ou défini sur une chaîne vide, aucun lien « vers le haut » ne sera fourni dans les documents.
Spécifiez le nom d'un modèle de document dans lequel la documentation sur les variables doit être insérée à partir de tous les fichiers du projet. Ceci est utile si le code source variable est dispersé dans de nombreux fichiers et que vous devez le regrouper en un seul endroit. Vous êtes responsable de vous assurer que le modèle de document de base (dans lequel la documentation des variables individuelles est insérée) contient toutes les autres informations souhaitées, mais pour plus de commodité, autogsdoc générera un modèle simple (que vous pourrez ensuite modifier) pour vous si le fichier ne n'existe pas. L'insertion a lieu juste avant l'élément back (ou s'il n'existe pas, juste avant la fin de l'élément body) dans le modèle.
Un booléen utilisé pour spécifier si vous voulez qu'une sortie de débogage/avertissement détaillée soit produite.
Un booléen utilisé pour spécifier si vous souhaitez que la sortie d'avertissement standard (par exemple, un rapport de méthodes non documentées) soit produite.
Cette valeur est un dictionnaire utilisé pour mapper les identifiants/mots-clés trouvés dans les fichiers source à d'autres mots. Généralement, vous n'aurez pas à l'utiliser, mais il est parfois utile d'éviter que l'analyseur ne soit confus par l'utilisation de macros de préprocesseur C. Vous pouvez redéfinir efficacement la macro en quelque chose de moins déroutant. La valeur à laquelle vous mappez l'identifiant doit être l'une des suivantes : - Un autre identifiant, Une chaîne vide - la valeur est ignorée, Deux barres obliques ('//') - le reste de la ligne est ignoré. Notez qu'un dictionnaire peut être donné sur la ligne de commande en utilisant le format standard PropertyList (et non le format XML d'OS X), en utilisant des points-virgules comme séparateurs de ligne et en l'entourant de guillemets simples.
La valeur par défaut « Haut » est utilisée pour spécifier le nom d'un document qui doit être utilisé comme lien « Haut » pour tout autre document utilisé. Ce nom ne doit pas inclure de chemin ni d'extension. Généralement, le document auquel il est fait référence par défaut doit être un document GSDoc édité manuellement qui doit avoir une section back contenant un index de projet. par exemple.
<?xml version="1.0"?>
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 1.0.3//EN"
"http://www.gnustep.org/gsdoc-1_0_3.xml">
<gsdoc base="index">
<head>
<title>My project reference</title>
<author name="my name"></author>
</head>
<body>
<chapter>
<heading>My project reference</heading>
</chapter>
<back>
<index scope="project" type="title" />
</back>
</body>
</gsdoc> Source: .h, .m, .c
GSDoc: .gsdoc
Index: .igsdoc
HTML: .htmlPlusieurs éléments GSDoc ne sont pas encore rendus correctement en HTML. Ce sont :
Les messages d'erreur et les avertissements peuvent provenir de chacune des étapes du pipeline : contrôle de niveau supérieur, analyse source, analyse GSDoc et indexation.
gsdoc(7), GNUstep(7)
Autogsdoc combinait les capacités de deux outils antérieurs, "autodoc" et "gsdoc", qui effectuaient respectivement les traductions source->GSDoc et GSDoc->HTML. Ces outils antérieurs et le format GSDoc ont été développés pour GNUstep sur la base de l'ancien langage GDML SGML.
Cette page de manuel est apparue pour la première fois dans gnustep-base 1.9.2 (mars 2004).
autogsdoc a été écrit par Richard Frith-Macdonald rfm@gnu.org
Cette page de manuel a été ajoutée par Adrian Robert arobert@cogsci.ucsd.edu.