Sortie du module Perl

Depuis la version 1.2.18, Doxygen peut générer un nouveau format de sortie que nous avons appelé le « format de sortie du module Perl ». Il a été conçu comme un format intermédiaire qui peut être utilisé pour générer une sortie nouvelle et personnalisée sans avoir à modifier la source Doxygen. Par conséquent, son objectif est similaire au format de sortie XML qui peut également être généré par Doxygen. Le format de sortie XML est plus standard, mais le format de sortie du module Perl est probablement plus simple et plus facile à utiliser.

Le format de sortie du module Perl est encore expérimental pour le moment et pourrait être modifié de manière incompatible dans les versions futures, bien que cela ne soit pas très probable. Il manque également certaines fonctionnalités d'autres backends Doxygen. Cependant, il peut déjà être utilisé pour générer une sortie utile, comme le montre le générateur basé sur le module Perl.

Veuillez signaler tout bug ou problème que vous trouvez dans le backend du module Perl ou le générateur basé sur le module Perl au suivi des problèmes de Doxygen. Les suggestions sont également les bienvenues (voir aussi : Comment signaler un bug).

Utilisation

Lorsque la balise GENERATE_PERLMOD est activée dans le fichier Doxyfile, l'exécution de Doxygen génère un certain nombre de fichiers dans le sous-répertoire perlmod/ de votre répertoire de sortie. Ces fichiers sont les suivants :

• DoxyDocs.pm : Il s'agit du module Perl qui contient réellement la documentation, au format du module Perl décrit ci-dessous.

• DoxyModel.pm: Ce module Perl décrit la structure de DoxyDocs.pm, indépendamment de la documentation proprement dite. Voir **ci-dessous** pour plus de détails.

• doxyrules.make : Ce fichier contient les règles de création pour construire et nettoyer les fichiers générés à partir du fichier Doxyfile. Contient également les chemins d'accès à ces fichiers et d'autres informations pertinentes. Ce fichier est destiné à être inclus dans votre propre fichier Makefile.

• Makefile : Il s'agit d'un simple fichier Makefile incluant doxyrules.make.

Pour utiliser la documentation stockée dans DoxyDocs.pm, vous pouvez utiliser l'un des générateurs basés sur le module Perl par défaut fournis par Doxygen (pour le moment, cela inclut le générateur basé sur le module Perl, voir ci-dessous) ou écrire votre propre générateur personnalisé. Cela ne devrait pas être trop difficile si vous avez quelques connaissances de Perl et c'est le but principal de l'inclusion du backend du module Perl dans Doxygen. Voir ci-dessous pour plus de détails sur la façon de procéder.

Utilisation du générateur LaTeX.

Le générateur basé sur le module Perl est assez expérimental et incomplet pour le moment, mais vous pourriez néanmoins le trouver utile. Il peut générer de la documentation pour les fonctions, les définitions de type et les variables dans les fichiers et les classes et peut être personnalisé de manière assez importante en redéfinissant les macros . Cependant, il n'existe toujours pas de documentation sur la façon de procéder.

La définition de la balise PERLMOD_LATEX sur YES dans le fichier Doxyfile permet la création de fichiers supplémentaires dans le sous-répertoire perlmod/ de votre répertoire de sortie. Ces fichiers contiennent les scripts Perl et le code nécessaires pour générer des sorties PDF et DVI à partir de la sortie du module Perl, en utilisant respectivement pdflatex et latex. Des règles pour automatiser l'utilisation de ces fichiers sont également ajoutées à doxyrules.make et au Makefile.

Les fichiers supplémentaires générés sont les suivants :

• doxylatex.pl : ce script Perl utilise DoxyDocs.pm et DoxyModel.pm pour générer doxydocs.tex, un fichier contenant la documentation dans un format accessible par le code . Ce fichier n'est pas directement LaTeXable.

• doxyformat.tex : ce fichier contient le code qui transforme la documentation de doxydocs.tex en texte pouvant être 'ed et présenté à l'utilisateur.

• doxylatex-template.pl : ce script Perl utilise DoxyModel.pm pour générer doxytemplate.tex, un fichier définissant les valeurs par défaut de certaines macros. doxytemplate.tex est inclus dans doxyformat.tex pour éviter la nécessité de définir explicitement certaines macros.

• doxylatex.tex : il s'agit d'un document très simple qui charge certains paquets et inclut doxyformat.tex et doxydocs.tex. Ce document est 'ed pour produire la documentation PDF et DVI selon les règles ajoutées à doxyrules.make.

Création de sorties PDF et DVI

Pour essayer cela, vous devez avoir installé latex, pdflatex et les paquets utilisés par doxylatex.tex.

1 . Mettez à jour votre Doxyfile vers la dernière version en utilisant :

doxygen -u Doxyfile

2 .Définissez les balises GENERATE_PERLMOD et PERLMOD_LATEX sur YES dans votre Doxyfile.

3 . Exécutez Doxygen sur votre Doxyfile :

doxygen Doxyfile

4 . Un sous-répertoire perlmod/ doit apparaître dans votre répertoire de sortie. Entrez dans le sous-répertoire perlmod/ et exécutez :

make pdf

Cela devrait générer un doxylatex.pdf avec la documentation au format PDF.

5 . Exécutez :

make dvi

Cela devrait générer un doxylatex.dvi avec la documentation au format DVI.

Format de la documentation.

La documentation du module Perl générée par Doxygen est stockée dans DoxyDocs.pm. Il s'agit d'un module Perl très simple qui ne contient que deux instructions : une affectation à la variable $doxydocs et l'instruction habituelle 1 ; qui termine généralement les modules Perl.

La documentation est stockée dans la variable $doxydocs, à laquelle on peut ensuite accéder par un script Perl utilisant DoxyDocs.pm.

$doxydocs contient une structure arborescente composée de trois types de nœuds : chaînes, hachages et listes.

• Strings : ce sont des chaînes Perl normales. Elles peuvent être de n'importe quelle longueur et contenir n'importe quel caractère. Leur sémantique dépend de leur emplacement dans l'arbre. Ce type de nœud n'a pas d'enfants.

• Hashes : ce sont des références à des hachages Perl anonymes. Un hachage peut avoir plusieurs champs, chacun avec une clé différente. La valeur d'un champ de hachage peut être une chaîne, un hachage ou une liste, et sa sémantique dépend de la clé du champ de hachage et de l'emplacement du hachage dans l'arbre. Les valeurs des champs de hachage sont les enfants du nœud.

• Lists : Ce sont des références à des listes Perl anonymes. Une liste comporte un nombre indéfini d'éléments, qui sont les enfants du nœud. Chaque élément a le même type (chaîne, hachage ou liste) et la même sémantique, selon l'emplacement de la liste dans l'arbre.

Comme vous pouvez le constater, la documentation contenue dans $doxydocs ne présente aucun obstacle particulier à être traitée par un simple script Perl.

Structure de données

Vous pourriez être intéressé pour traiter la documentation contenue dans DoxyDocs.pm sans avoir besoin de prendre en compte la sémantique de chaque nœud de l'arbre de documentation. À cette fin, Doxygen génère un fichier DoxyModel.pm qui contient une structure de données décrivant le type et les enfants de chaque nœud de l'arbre de documentation.

Le reste de cette section reste à écrire, mais en attendant, vous pouvez consulter les scripts Perl générés par Doxygen (tels que doxylatex.pl ou doxytemplate-latex.pl) pour vous faire une idée de la façon d'utiliser DoxyModel.pm.

Nœuds d'arborescence de modules Perl

Nœuds dans l'arborescence de la documentation du format de sortie du module Perl.

Voici une description de la structure de l'arborescence de la documentation dans DoxyDocs.pm. Chaque élément de la liste ci-dessous décrit un nœud de l'arborescence, et le format de la description est le suivant :

• [ key => ] Name (type). Explication du contenu.

Où

• La partie « key => » n'apparaît que si le nœud parent est un hachage. « key » est la clé de ce nœud.

• « Name » est un nom unique pour le nœud, défini dans DoxyModel.pm.

• « (type) » est le type du nœud : « string » pour les nœuds de chaîne, « hash » pour les nœuds de hachage, « list » pour les nœuds de liste et « doc » pour les sous-arborescences de documentation. La structure des sous-arborescences de documentation n'est encore décrite nulle part, mais vous pouvez consulter par exemple doxylatex.pl pour voir comment la traiter.

La signification de chaque nœud dans l'arborescence de la documentation est la suivante :

• Root (hash). Root node.
  • classes => Classes (list). Documented classes.
    • Class (hash). A documented class.
      • protected_members => ClassProtectedMembers (hash). Information about the protected members in the class.
        • members => ClassProtectedMemberList (list). protected member list.
          • ClassProtectedMember (hash). A protected member.
            • protection => ClassProtectedMemberProtection (string). Protection of the protected member.
            • detailed => ClassProtectedMemberDetailed (hash). Detailed information about the protected member.
              • doc => ClassProtectedMemberDetailedDoc (doc). Detailed documentation for the protected member.
              • see => ClassProtectedMemberSee (doc). "See also" documentation for the protected member.
            • kind => ClassProtectedMemberKind (string). Kind of protected member (usually "variable").
            • name => ClassProtectedMemberName (string). Name of the protected member.
            • type => ClassProtectedMemberType (string). Data type of the protected member.
      • detailed => ClassDetailed (hash). Detailed information about the class.
        • doc => ClassDetailedDoc (doc). Detailed documentation block for the class.
      • protected_typedefs => ClassProtectedTypedefs (hash). Information about the protected typedefs in the class.
        • members => ClassProtectedTypedefList (list). protected typedef list.
          • ClassProtectedTypedef (hash). A protected typedef.
            • protection => ClassProtectedTypedefProtection (string). Protection of the protected typedef.
            • detailed => ClassProtectedTypedefDetailed (hash). Detailed information about the protected typedef.
              • doc => ClassProtectedTypedefDetailedDoc (doc). Detailed documentation for the protected typedef.
              • see => ClassProtectedTypedefSee (doc). "See also" documentation for the protected typedef.
            • kind => ClassProtectedTypedefKind (string). Kind of protected typedef (usually "typedef").
            • name => ClassProtectedTypedefName (string). Name of the protected typedef.
            • type => ClassProtectedTypedefType (string). Data type of the protected typedef.
      • name => ClassName (string). Name of the class.
      • private_members => ClassPrivateMembers (hash). Information about the private members in the class.
        • members => ClassPrivateMemberList (list). private member list.
          • ClassPrivateMember (hash). A private member.
            • protection => ClassPrivateMemberProtection (string). Protection of the private member.
            • detailed => ClassPrivateMemberDetailed (hash). Detailed information about the private member.
              • doc => ClassPrivateMemberDetailedDoc (doc). Detailed documentation for the private member.
              • see => ClassPrivateMemberSee (doc). "See also" documentation for the private member.
            • kind => ClassPrivateMemberKind (string). Kind of private member (usually "variable").
            • name => ClassPrivateMemberName (string). Name of the private member.
            • type => ClassPrivateMemberType (string). Data type of the private member.
      • private_typedefs => ClassPrivateTypedefs (hash). Information about the private typedefs in the class.
        • members => ClassPrivateTypedefList (list). private typedef list.
          • ClassPrivateTypedef (hash). A private typedef.
            • protection => ClassPrivateTypedefProtection (string). Protection of the private typedef.
            • detailed => ClassPrivateTypedefDetailed (hash). Detailed information about the private typedef.
              • doc => ClassPrivateTypedefDetailedDoc (doc). Detailed documentation for the private typedef.
              • see => ClassPrivateTypedefSee (doc). "See also" documentation for the private typedef.
            • kind => ClassPrivateTypedefKind (string). Kind of private typedef (usually "typedef").
            • name => ClassPrivateTypedefName (string). Name of the private typedef.
            • type => ClassPrivateTypedefType (string). Data type of the private typedef.
      • protected_methods => ClassProtectedMethods (hash). Information about the protected methods in the class.
        • members => ClassProtectedMethodList (list). protected method list.
          • ClassProtectedMethod (hash). A protected method.
            • parameters => ClassProtectedMethodParams (list). List of the parameters of the protected method.
              • ClassProtectedMethodParam (hash). A parameter of the protected method.
                • declaration_name => ClassProtectedMethodParamName (string). The name of the parameter.
                • type => ClassProtectedMethodParamType (string). The data type of the parameter.
            • protection => ClassProtectedMethodProtection (string). Protection of the protected method.
            • virtualness => ClassProtectedMethodVirtualness (string). Virtualness of the protected method.
            • detailed => ClassProtectedMethodDetailed (hash). Detailed information about the protected method.
              • params => ClassProtectedMethodPDBlocks (list). List of parameter documentation blocks for the protected method.
                • ClassProtectedMethodPDBlock (hash). A parameter documentation block for the protected method.
                  • parameters => ClassProtectedMethodPDParams (list). Parameter list for this parameter documentation block.
                    • ClassProtectedMethodPDParam (hash). A parameter documented by this documentation block.
                      • name => ClassProtectedMethodPDParamName (string). Name of the parameter.
                  • doc => ClassProtectedMethodPDDoc (doc). Documentation for this parameter documentation block.
              • doc => ClassProtectedMethodDetailedDoc (doc). Detailed documentation for the protected method.
              • see => ClassProtectedMethodSee (doc). "See also" documentation for the protected method.
              • return => ClassProtectedMethodReturn (doc). Documentation about the return value of the protected method.
            • kind => ClassProtectedMethodKind (string). Kind of protected method (usually "function").
            • name => ClassProtectedMethodName (string). Name of the protected method.
            • type => ClassProtectedMethodType (string). Data type returned by the protected method.
            • static => ClassProtectedMethodStatic (string). Whether the protected method is static.
      • public_typedefs => ClassPublicTypedefs (hash). Information about the public typedefs in the class.
        • members => ClassPublicTypedefList (list). public typedef list.
          • ClassPublicTypedef (hash). A public typedef.
            • protection => ClassPublicTypedefProtection (string). Protection of the public typedef.
            • detailed => ClassPublicTypedefDetailed (hash). Detailed information about the public typedef.
              • doc => ClassPublicTypedefDetailedDoc (doc). Detailed documentation for the public typedef.
              • see => ClassPublicTypedefSee (doc). "See also" documentation for the public typedef.
            • kind => ClassPublicTypedefKind (string). Kind of public typedef (usually "typedef").
            • name => ClassPublicTypedefName (string). Name of the public typedef.
            • type => ClassPublicTypedefType (string). Data type of the public typedef.
      • public_members => ClassPublicMembers (hash). Information about the public members in the class.
        • members => ClassPublicMemberList (list). public member list.
          • ClassPublicMember (hash). A public member.
            • protection => ClassPublicMemberProtection (string). Protection of the public member.
            • detailed => ClassPublicMemberDetailed (hash). Detailed information about the public member.
              • doc => ClassPublicMemberDetailedDoc (doc). Detailed documentation for the public member.
              • see => ClassPublicMemberSee (doc). "See also" documentation for the public member.
            • kind => ClassPublicMemberKind (string). Kind of public member (usually "variable").
            • name => ClassPublicMemberName (string). Name of the public member.
            • type => ClassPublicMemberType (string). Data type of the public member.
      • private_methods => ClassPrivateMethods (hash). Information about the private methods in the class.
        • members => ClassPrivateMethodList (list). private method list.
          • ClassPrivateMethod (hash). A private method.
            • parameters => ClassPrivateMethodParams (list). List of the parameters of the private method.
              • ClassPrivateMethodParam (hash). A parameter of the private method.
                • declaration_name => ClassPrivateMethodParamName (string). The name of the parameter.
                • type => ClassPrivateMethodParamType (string). The data type of the parameter.
            • protection => ClassPrivateMethodProtection (string). Protection of the private method.
            • virtualness => ClassPrivateMethodVirtualness (string). Virtualness of the private method.
            • detailed => ClassPrivateMethodDetailed (hash). Detailed information about the private method.
              • params => ClassPrivateMethodPDBlocks (list). List of parameter documentation blocks for the private method.
                • ClassPrivateMethodPDBlock (hash). A parameter documentation block for the private method.
                  • parameters => ClassPrivateMethodPDParams (list). Parameter list for this parameter documentation block.
                    • ClassPrivateMethodPDParam (hash). A parameter documented by this documentation block.
                      • name => ClassPrivateMethodPDParamName (string). Name of the parameter.
                  • doc => ClassPrivateMethodPDDoc (doc). Documentation for this parameter documentation block.
              • doc => ClassPrivateMethodDetailedDoc (doc). Detailed documentation for the private method.
              • see => ClassPrivateMethodSee (doc). "See also" documentation for the private method.
              • return => ClassPrivateMethodReturn (doc). Documentation about the return value of the private method.
            • kind => ClassPrivateMethodKind (string). Kind of private method (usually "function").
            • name => ClassPrivateMethodName (string). Name of the private method.
            • type => ClassPrivateMethodType (string). Data type returned by the private method.
            • static => ClassPrivateMethodStatic (string). Whether the private method is static.
      • public_methods => ClassPublicMethods (hash). Information about the public methods in the class.
        • members => ClassPublicMethodList (list). public method list.
          • ClassPublicMethod (hash). A public method.
            • parameters => ClassPublicMethodParams (list). List of the parameters of the public method. *ClassPublicMethodParam (hash). A parameter of the public method. * declaration_name => ClassPublicMethodParamName (string). The name of the parameter. * type => ClassPublicMethodParamType (string). The data type of the parameter.
            • protection => ClassPublicMethodProtection (string). Protection of the public method.
            • virtualness => ClassPublicMethodVirtualness (string). Virtualness of the public method.
            • detailed => ClassPublicMethodDetailed (hash). Detailed information about the public method.
              • params => ClassPublicMethodPDBlocks (list). List of parameter documentation blocks for the public method.
                • ClassPublicMethodPDBlock (hash). A parameter documentation block for the public method.
                  • parameters => ClassPublicMethodPDParams (list). Parameter list for this parameter documentation block.
                    • ClassPublicMethodPDParam (hash). A parameter documented by this documentation block.
                      • name => ClassPublicMethodPDParamName (string). Name of the parameter.
                  • doc => ClassPublicMethodPDDoc (doc). Documentation for this parameter documentation block.
          • doc => ClassPublicMethodDetailedDoc (doc). Detailed documentation for the public method.
          • see => ClassPublicMethodSee (doc). "See also" documentation for the public method.
          • return => ClassPublicMethodReturn (doc). Documentation about the return value of the public method.
        • kind => ClassPublicMethodKind (string). Kind of public method (usually "function").
        • name => ClassPublicMethodName (string). Name of the public method.
        • type => ClassPublicMethodType (string). Data type returned by the public method.
        • static => ClassPublicMethodStatic (string). Whether the public method is static.
• files => Files (list). Documented files.
  • File (hash). A documented file.
    • detailed => FileDetailed (hash). Detailed information about the file.
      • doc => FileDetailedDoc (doc). Detailed documentation block for the file.
    • functions => FileFunctions (hash). Information about the functions in the file.
      • members => FileFunctionList (list). function list.
      • FileFunction (hash). A function.
        • parameters => FileFunctionParams (list). List of the parameters of the function.
          • FileFunctionParam (hash). A parameter of the function.
            • declaration_name => FileFunctionParamName (string). The name of the parameter.
            • type => FileFunctionParamType (string). The data type of the parameter.
        • protection => FileFunctionProtection (string). Protection of the function.
        • virtualness => FileFunctionVirtualness (string). Virtualness of the function.
        • detailed => FileFunctionDetailed (hash). Detailed information about the function.
          • params => FileFunctionPDBlocks (list). List of parameter documentation blocks for the function.
            • FileFunctionPDBlock (hash). A parameter documentation block for the function.
            • parameters => FileFunctionPDParams (list). Parameter list for this parameter documentation block.
              • FileFunctionPDParam (hash). A parameter documented by this documentation block.
                • name => FileFunctionPDParamName (string). Name of the parameter.
            • doc => FileFunctionPDDoc (doc). Documentation for this parameter documentation block.
          • doc => FileFunctionDetailedDoc (doc). Detailed documentation for the function.
          • see => FileFunctionSee (doc). "See also" documentation for the function.
          • return => FileFunctionReturn (doc). Documentation about the return value of the function.
        • kind => FileFunctionKind (string). Kind of function (usually "function").
        • name => FileFunctionName (string). Name of the function.
        • type => FileFunctionType (string). Data type returned by the function.
        • static => FileFunctionStatic (string). Whether the function is static.
      • name => FileName (string). Name of the file.
      • variables => FileVariables (hash). Information about the variables in the file.
      • members => FileVariableList (list). variable list.
        • FileVariable (hash). A variable.
          • protection => FileVariableProtection (string). Protection of the variable.
          • detailed => FileVariableDetailed (hash). Detailed information about the variable.
            • doc => FileVariableDetailedDoc (doc). Detailed documentation for the variable.
            • see => FileVariableSee (doc). "See also" documentation for the variable.
          • kind => FileVariableKind (string). Kind of variable (usually "variable").
          • name => FileVariableName (string). Name of the variable.
          • type => FileVariableType (string). Data type of the variable.
      • typedefs => FileTypedefs (hash). Information about the typedefs in the file.
      • members => FileTypedefList (list). typedef list.
        • FileTypedef (hash). A typedef.
          • protection => FileTypedefProtection (string). Protection of the typedef.
          • detailed => FileTypedefDetailed (hash). Detailed information about the typedef.
            • doc => FileTypedefDetailedDoc (doc). Detailed documentation for the typedef.
            • see => FileTypedefSee (doc). "See also" documentation for the typedef.
          • kind => FileTypedefKind (string). Kind of typedef (usually "typedef").
          • name => FileTypedefName (string). Name of the typedef.
          • type => FileTypedefType (string). Data type of the typedef.