ドキュメント 変更履歴 拡張機能 例  
Perlモジュール出力

バージョン1.2.18以降、Doxygenは「Perlモジュール出力形式」と呼ぶ新しい出力形式を生成できるようになりました。これは、Doxygenのソースを修正することなく、新しいカスタマイズされた出力を生成するために使用できる中間形式として設計されました。したがって、その目的はDoxygenによって生成できるXML出力形式と似ています。XML出力形式の方がより標準的ですが、Perlモジュール出力形式は、おそらくよりシンプルで使いやすいでしょう。

Perlモジュール出力形式は現在まだ実験段階であり、将来のバージョンで互換性のない変更が行われる可能性がありますが、これはあまり起こりそうにありません。また、他のDoxygenバックエンドのいくつかの機能が不足しています。しかし、PerlモジュールベースのLaTeXジェネレーターが示しているように、すでに有用な出力を生成するために使用できます。

PerlモジュールバックエンドまたはPerlモジュールベースのLaTeXジェネレーターで見つかったバグや問題は、Doxygenイシュートラッカーに報告してください。提案も歓迎します（参照: バグの報告方法）。

使用方法

DoxyfileでGENERATE_PERLMODタグが有効になっている場合、Doxygenを実行すると、出力ディレクトリのperlmod/サブディレクトリにいくつかのファイルが生成されます。これらのファイルは以下のとおりです。

  • DoxyDocs.pm: これは、実際にドキュメントを、以下に記述されているPerlモジュール形式で含んでいるPerlモジュールです。

  • DoxyModel.pm: このPerlモジュールは、実際のドキュメントとは独立して、DoxyDocs.pmの構造を記述します。詳細は以下を参照してください。

  • doxyrules.make: このファイルには、Doxyfileから生成されるファイルをビルドおよびクリーンアップするためのmakeルールが含まれています。また、これらのファイルへのパスやその他の関連情報も含まれています。このファイルは、独自のMakefileに含めることを意図しています。

  • Makefile: これは、doxyrules.makeを含むシンプルなMakefileです。

DoxyDocs.pmに保存されているドキュメントを利用するには、Doxygenが提供するデフォルトのPerlモジュールベースのジェネレーターのいずれかを使用するか（現時点ではPerlモジュールベースのLaTeXジェネレーターが含まれます、以下を参照）、または独自のカスタマイズされたジェネレーターを作成することができます。Perlの知識があればそれほど難しくないはずであり、これがDoxygenにPerlモジュールバックエンドを含める主な目的です。これを行う方法の詳細は、以下を参照してください。

LaTeXジェネレーターの使用。

PerlモジュールベースのLaTeXジェネレーターは、現在かなり実験的で不完全ですが、それでも便利に感じるかもしれません。ファイル内およびクラス内の関数、typedef、変数のドキュメントを生成でき、TeXマクロを再定義することでかなりカスタマイズできます。ただし、これを行う方法に関するドキュメントはまだありません。

DoxyfileでPERLMOD_LATEXタグを`YES`に設定すると、出力ディレクトリのperlmod/サブディレクトリにいくつかの追加ファイルの作成が有効になります。これらのファイルには、pdflatexおよびlatexを使用して、Perlモジュール出力からそれぞれPDFおよびDVI出力を生成するために必要なPerlスクリプトとLaTeXコードが含まれています。これらのファイルの利用を自動化するためのルールも、doxyrules.makeおよびMakefileに追加されます。

追加で生成されるファイルは以下のとおりです。

  • doxylatex.pl: このPerlスクリプトは、DoxyDocs.pmとDoxyModel.pmを使用して、LaTeXコードからアクセス可能な形式でドキュメントを含むTeXファイルであるdoxydocs.texを生成します。このファイルは直接LaTeX処理できません。

  • doxyformat.tex: このファイルには、doxydocs.texからのドキュメントを、LaTeX処理されてユーザーに提示されるのに適したLaTeXテキストに変換するLaTeXコードが含まれています。

  • doxylatex-template.pl: このPerlスクリプトは、DoxyModel.pmを使用して、いくつかのマクロのデフォルト値を定義するTeXファイルであるdoxytemplate.texを生成します。doxyformat.texはdoxytemplate.texをインクルードし、いくつかのマクロを明示的に定義する必要をなくします。

  • doxylatex.tex: これは、いくつかのパッケージをロードし、doxyformat.texとdoxydocs.texをインクルードする非常にシンプルなLaTeXドキュメントです。このドキュメントは、doxyrules.makeに追加されたルールにより、PDFおよびDVIドキュメントを生成するためにLaTeX処理されます。

PDFおよびDVI出力の作成

これを試すには、latex、pdflatex、およびdoxylatex.texで使用されるパッケージがインストールされている必要があります。

  1. 以下のコマンドを使用して、Doxyfileを最新バージョンに更新してください。

    doxygen -u Doxyfile

  2. DoxyfileでGENERATE_PERLMODおよびPERLMOD_LATEXタグの両方を`YES`に設定してください。

  3. Doxyfileに対してDoxygenを実行してください

    doxygen Doxyfile

  4. 出力ディレクトリにperlmod/サブディレクトリが出現しているはずです。perlmod/サブディレクトリに入り、以下を実行してください

    make pdf

    これにより、ドキュメントがPDF形式で含まれるdoxylatex.pdfが生成されるはずです。

  5. 以下を実行してください

    make dvi

    これにより、ドキュメントがDVI形式で含まれるdoxylatex.dviが生成されるはずです。

ドキュメント形式。

Doxygenによって生成されたPerlモジュールドキュメントは、DoxyDocs.pmに保存されます。これは、変数$doxydocsへの代入と、通常Perlモジュールの最後にある慣習的な1;ステートメントの2つのステートメントのみを含む非常にシンプルなPerlモジュールです。
ドキュメントは変数$doxydocsに保存されており、DoxyDocs.pmを使用するPerlスクリプトによってアクセスできます。

$doxydocsは、文字列、ハッシュ、リストの3種類のノードで構成されるツリー状の構造を含んでいます。

  • Strings (文字列): これらは通常のPerl文字列です。任意の長さで、任意の文字を含むことができます。そのセマンティクスは、ツリー内の位置によって異なります。このタイプのノードには子ノードがありません。

  • Hashes (ハッシュ): これらは無名Perlハッシュへの参照です。ハッシュは複数のフィールドを持つことができ、それぞれ異なるキーを持ちます。ハッシュフィールドの値は、文字列、ハッシュ、またはリストである可能性があり、そのセマンティクスはハッシュフィールドのキーとツリー内のハッシュの位置に依存します。ハッシュフィールドの値がノードの子ノードになります。

  • Lists (リスト): これらは無名Perlリストへの参照です。リストは不定数の要素を持ち、それらがノードの子ノードとなります。各要素は同じ型（文字列、ハッシュ、リスト）と同じセマンティクスを持ち、ツリー内のリストの位置によって異なります。

ご覧のとおり、$doxydocsに含まれるドキュメントは、シンプルなPerlスクリプトで処理する上で特別な障害は何もありません。

データ構造

DoxyDocs.pmに含まれるドキュメントを、ドキュメントツリーの各ノードのセマンティクスを考慮することなく処理することに関心があるかもしれません。この目的のために、DoxygenはDoxyModel.pmファイルを生成します。このファイルには、ドキュメントツリー内の各ノードの型と子ノードを記述するデータ構造が含まれています。

このセクションの残りの部分はまだ執筆されていませんが、その間にDoxygenによって生成されたPerlスクリプト（doxylatex.plやdoxytemplate-latex.plなど）を見て、DoxyModel.pmの使い方のヒントを得ることができます。

Perlモジュールツリーノード

Perlモジュール出力形式のドキュメントツリー内のノード。

これは、DoxyDocs.pmにおけるドキュメントツリーの構造の説明です。以下のリストの各項目は、ツリー内のノードを記述しており、説明の形式は以下のとおりです

  • [ key => ] 名前 (型). 内容の説明。

ここで

  • 「key =>」の部分は、親ノードがハッシュの場合にのみ表示されます。「key」はこのノードのキーです。

  • 「名前」は、DoxyModel.pmで定義されているノードの一意の名前です。

  • 「(型)」はノードの型です: 文字列ノードの場合は「string」、ハッシュノードの場合は「hash」、リストノードの場合は「list」、ドキュメントサブツリーの場合は「doc」です。ドキュメントサブツリーの構造はまだどこにも記述されていませんが、例えばdoxylatex.plを見て、その処理方法を確認することができます。

ドキュメントツリー内の各ノードの意味は以下のとおりです

  • Root (hash). ルートノード。
    • classes => Classes (list). ドキュメント化されたクラス。
      • Class (hash). ドキュメント化されたクラス。
        • protected_members => ClassProtectedMembers (hash). クラス内の保護メンバーに関する情報。
          • members => ClassProtectedMemberList (list). 保護メンバーのリスト。
            • ClassProtectedMember (hash). 保護メンバー。
              • protection => ClassProtectedMemberProtection (string). 保護メンバーの保護レベル。
              • detailed => ClassProtectedMemberDetailed (hash). 保護メンバーに関する詳細情報。
                • doc => ClassProtectedMemberDetailedDoc (doc). 保護メンバーの詳細ドキュメント。
                • see => ClassProtectedMemberSee (doc). 保護メンバーの「関連項目」ドキュメント。
              • kind => ClassProtectedMemberKind (string). 保護メンバーの種別（通常は「variable」）。
              • name => ClassProtectedMemberName (string). 保護メンバーの名前。
              • type => ClassProtectedMemberType (string). 保護メンバーのデータ型。
        • detailed => ClassDetailed (hash). クラスに関する詳細情報。
          • doc => ClassDetailedDoc (doc). クラスの詳細ドキュメントブロック。
        • protected_typedefs => ClassProtectedTypedefs (hash). クラス内の保護されたtypedefに関する情報。
          • members => ClassProtectedTypedefList (list). 保護されたtypedefのリスト。
            • ClassProtectedTypedef (hash). 保護されたtypedef。
              • protection => ClassProtectedTypedefProtection (string). 保護されたtypedefの保護レベル。
              • detailed => ClassProtectedTypedefDetailed (hash). 保護されたtypedefに関する詳細情報。
                • doc => ClassProtectedTypedefDetailedDoc (doc). 保護されたtypedefの詳細ドキュメント。
                • see => ClassProtectedTypedefSee (doc). 保護されたtypedefの「関連項目」ドキュメント。
              • kind => ClassProtectedTypedefKind (string). 保護されたtypedefの種別（通常は「typedef」）。
              • name => ClassProtectedTypedefName (string). 保護されたtypedefの名前。
              • type => ClassProtectedTypedefType (string). 保護されたtypedefのデータ型。
        • name => ClassName (string). クラスの名前。
        • private_members => ClassPrivateMembers (hash). クラス内のプライベートメンバーに関する情報。
          • members => ClassPrivateMemberList (list). プライベートメンバーのリスト。
            • ClassPrivateMember (hash). プライベートメンバー。
              • protection => ClassPrivateMemberProtection (string). プライベートメンバーの保護レベル。
              • detailed => ClassPrivateMemberDetailed (hash). プライベートメンバーに関する詳細情報。
                • doc => ClassPrivateMemberDetailedDoc (doc). プライベートメンバーの詳細ドキュメント。
                • see => ClassPrivateMemberSee (doc). プライベートメンバーの「関連項目」ドキュメント。
              • kind => ClassPrivateMemberKind (string). プライベートメンバーの種別（通常は「variable」）。
              • name => ClassPrivateMemberName (string). プライベートメンバーの名前。
              • type => ClassPrivateMemberType (string). プライベートメンバーのデータ型。
        • private_typedefs => ClassPrivateTypedefs (hash). クラス内のプライベートtypedefに関する情報。
          • members => ClassPrivateTypedefList (list). プライベートtypedefのリスト。
            • ClassPrivateTypedef (hash). プライベートtypedef。
              • protection => ClassPrivateTypedefProtection (string). プライベートtypedefの保護レベル。
              • detailed => ClassPrivateTypedefDetailed (hash). プライベートtypedefに関する詳細情報。
                • doc => ClassPrivateTypedefDetailedDoc (doc). プライベートtypedefの詳細ドキュメント。
                • see => ClassPrivateTypedefSee (doc). プライベートtypedefの「関連項目」ドキュメント。
              • kind => ClassPrivateTypedefKind (string). プライベートtypedefの種別（通常は「typedef」）。
              • name => ClassPrivateTypedefName (string). プライベートtypedefの名前。
              • type => ClassPrivateTypedefType (string). プライベートtypedefのデータ型。
        • protected_methods => ClassProtectedMethods (hash). クラス内の保護メソッドに関する情報。
          • members => ClassProtectedMethodList (list). 保護メソッドのリスト。
            • ClassProtectedMethod (hash). 保護メソッド。
              • parameters => ClassProtectedMethodParams (list). 保護メソッドのパラメーターのリスト。
                • ClassProtectedMethodParam (hash). 保護メソッドのパラメーター。
                  • declaration_name => ClassProtectedMethodParamName (string). パラメーターの名前。
                  • type => ClassProtectedMethodParamType (string). パラメーターのデータ型。
              • protection => ClassProtectedMethodProtection (string). 保護メソッドの保護レベル。
              • virtualness => ClassProtectedMethodVirtualness (string). 保護メソッドの仮想性。
              • detailed => ClassProtectedMethodDetailed (hash). 保護メソッドに関する詳細情報。
                • params => ClassProtectedMethodPDBlocks (list). 保護メソッドのパラメーターのドキュメントブロックのリスト。
                  • ClassProtectedMethodPDBlock (hash). 保護メソッドのパラメーターのドキュメントブロック。
                    • parameters => ClassProtectedMethodPDParams (list). このパラメーターのドキュメントブロックのパラメーターリスト。
                      • ClassProtectedMethodPDParam (hash). このドキュメントブロックでドキュメント化されたパラメーター。
                        • name => ClassProtectedMethodPDParamName (string). パラメーターの名前。
                    • doc => ClassProtectedMethodPDDoc (doc). このパラメーターのドキュメントブロックのドキュメント。
                • doc => ClassProtectedMethodDetailedDoc (doc). 保護メソッドの詳細ドキュメント。
                • see => ClassProtectedMethodSee (doc). 保護メソッドの「関連項目」ドキュメント。
                • return => ClassProtectedMethodReturn (doc). 保護メソッドの戻り値に関するドキュメント。
              • kind => ClassProtectedMethodKind (string). 保護メソッドの種別（通常は「function」）。
              • name => ClassProtectedMethodName (string). 保護メソッドの名前。
              • type => ClassProtectedMethodType (string). 保護メソッドによって返されるデータ型。
              • static => ClassProtectedMethodStatic (string). 保護メソッドが静的であるかどうか。
        • public_typedefs => ClassPublicTypedefs (hash). クラス内のパブリックtypedefに関する情報。
          • members => ClassPublicTypedefList (list). パブリックtypedefのリスト。
            • ClassPublicTypedef (hash). パブリックtypedef。
              • protection => ClassPublicTypedefProtection (string). パブリックtypedefの保護レベル。
              • detailed => ClassPublicTypedefDetailed (hash). パブリックtypedefに関する詳細情報。
                • doc => ClassPublicTypedefDetailedDoc (doc). パブリックtypedefの詳細ドキュメント。
                • see => ClassPublicTypedefSee (doc). パブリックtypedefの「関連項目」ドキュメント。
              • kind => ClassPublicTypedefKind (string). パブリックtypedefの種別（通常は「typedef」）。
              • name => ClassPublicTypedefName (string). パブリックtypedefの名前。
              • type => ClassPublicTypedefType (string). パブリックtypedefのデータ型。
        • public_members => ClassPublicMembers (hash). クラス内のパブリックメンバーに関する情報。
          • members => ClassPublicMemberList (list). パブリックメンバーのリスト。
            • ClassPublicMember (hash). パブリックメンバー。
              • protection => ClassPublicMemberProtection (string). パブリックメンバーの保護レベル。
              • detailed => ClassPublicMemberDetailed (hash). パブリックメンバーに関する詳細情報。
                • doc => ClassPublicMemberDetailedDoc (doc). パブリックメンバーの詳細ドキュメント。
                • see => ClassPublicMemberSee (doc). パブリックメンバーの「関連項目」ドキュメント。
              • kind => ClassPublicMemberKind (string). パブリックメンバーの種別（通常は「variable」）。
              • name => ClassPublicMemberName (string). パブリックメンバーの名前。
              • type => ClassPublicMemberType (string). パブリックメンバーのデータ型。
        • private_methods => ClassPrivateMethods (hash). クラス内のプライベートメソッドに関する情報。
          • members => ClassPrivateMethodList (list). プライベートメソッドのリスト。
            • ClassPrivateMethod (hash). プライベートメソッド。
              • parameters => ClassPrivateMethodParams (list). プライベートメソッドのパラメーターのリスト。
                • ClassPrivateMethodParam (hash). プライベートメソッドのパラメーター。
                  • declaration_name => ClassPrivateMethodParamName (string). パラメーターの名前。
                  • type => ClassPrivateMethodParamType (string). パラメーターのデータ型。
              • protection => ClassPrivateMethodProtection (string). プライベートメソッドの保護レベル。
              • virtualness => ClassPrivateMethodVirtualness (string). プライベートメソッドの仮想性。
              • detailed => ClassPrivateMethodDetailed (hash). プライベートメソッドに関する詳細情報。
                • params => ClassPrivateMethodPDBlocks (list). プライベートメソッドのパラメーターのドキュメントブロックのリスト。
                  • ClassPrivateMethodPDBlock (hash). プライベートメソッドのパラメーターのドキュメントブロック。
                    • parameters => ClassPrivateMethodPDParams (list). このパラメーターのドキュメントブロックのパラメーターリスト。
                      • ClassPrivateMethodPDParam (hash). このドキュメントブロックでドキュメント化されたパラメーター。
                        • name => ClassPrivateMethodPDParamName (string). パラメーターの名前。
                    • doc => ClassPrivateMethodPDDoc (doc). このパラメーターのドキュメントブロックのドキュメント。
                • doc => ClassPrivateMethodDetailedDoc (doc). プライベートメソッドの詳細ドキュメント。
                • see => ClassPrivateMethodSee (doc). プライベートメソッドの「関連項目」ドキュメント。
                • return => ClassPrivateMethodReturn (doc). プライベートメソッドの戻り値に関するドキュメント。
              • kind => ClassPrivateMethodKind (string). プライベートメソッドの種別（通常は「function」）。
              • name => ClassPrivateMethodName (string). プライベートメソッドの名前。
              • type => ClassPrivateMethodType (string). プライベートメソッドによって返されるデータ型。
              • static => ClassPrivateMethodStatic (string). プライベートメソッドが静的であるかどうか。
        • public_methods => ClassPublicMethods (hash). クラス内のパブリックメソッドに関する情報。
          • members => ClassPublicMethodList (list). パブリックメソッドのリスト。
            • ClassPublicMethod (hash). パブリックメソッド。
              • parameters => ClassPublicMethodParams (list). パブリックメソッドのパラメーターのリスト。
                • ClassPublicMethodParam (hash). パブリックメソッドのパラメーター。
                  • declaration_name => ClassPublicMethodParamName (string). パラメーターの名前。
                  • type => ClassPublicMethodParamType (string). パラメーターのデータ型。
              • protection => ClassPublicMethodProtection (string). パブリックメソッドの保護レベル。
              • virtualness => ClassPublicMethodVirtualness (string). パブリックメソッドの仮想性。
              • detailed => ClassPublicMethodDetailed (hash). パブリックメソッドに関する詳細情報。
                • params => ClassPublicMethodPDBlocks (list). パブリックメソッドのパラメーターのドキュメントブロックのリスト。
                  • ClassPublicMethodPDBlock (hash). パブリックメソッドのパラメーターのドキュメントブロック。
                    • parameters => ClassPublicMethodPDParams (list). このパラメーターのドキュメントブロックのパラメーターリスト。
                      • ClassPublicMethodPDParam (hash). このドキュメントブロックでドキュメント化されたパラメーター。
                        • name => ClassPublicMethodPDParamName (string). パラメーターの名前。
                    • doc => ClassPublicMethodPDDoc (doc). このパラメーターのドキュメントブロックのドキュメント。
                • doc => ClassPublicMethodDetailedDoc (doc). パブリックメソッドの詳細ドキュメント。
                • see => ClassPublicMethodSee (doc). パブリックメソッドの「関連項目」ドキュメント。
                • return => ClassPublicMethodReturn (doc). パブリックメソッドの戻り値に関するドキュメント。
              • kind => ClassPublicMethodKind (string). パブリックメソッドの種別（通常は「function」）。
              • name => ClassPublicMethodName (string). パブリックメソッドの名前。
              • type => ClassPublicMethodType (string). パブリックメソッドによって返されるデータ型。
              • static => ClassPublicMethodStatic (string). パブリックメソッドが静的であるかどうか。
    • files => Files (list). ドキュメント化されたファイル。
      • File (hash). ドキュメント化されたファイル。
        • detailed => FileDetailed (hash). ファイルに関する詳細情報。
          • doc => FileDetailedDoc (doc). ファイルの詳細ドキュメントブロック。
        • functions => FileFunctions (hash). ファイル内の関数に関する情報。
          • members => FileFunctionList (list). 関数のリスト。
            • FileFunction (hash). 関数。
              • parameters => FileFunctionParams (list). 関数のパラメーターのリスト。
                • FileFunctionParam (hash). 関数のパラメーター。
                  • declaration_name => FileFunctionParamName (string). パラメーターの名前。
                  • type => FileFunctionParamType (string). パラメーターのデータ型。
              • protection => FileFunctionProtection (string). 関数の保護レベル。
              • virtualness => FileFunctionVirtualness (string). 関数の仮想性。
              • detailed => FileFunctionDetailed (hash). 関数に関する詳細情報。
                • params => FileFunctionPDBlocks (list). 関数のパラメーターのドキュメントブロックのリスト。
                  • FileFunctionPDBlock (hash). 関数のパラメーターのドキュメントブロック。
                    • parameters => FileFunctionPDParams (list). このパラメーターのドキュメントブロックのパラメーターリスト。
                      • FileFunctionPDParam (hash). このドキュメントブロックでドキュメント化されたパラメーター。
                        • name => FileFunctionPDParamName (string). パラメーターの名前。
                    • doc => FileFunctionPDDoc (doc). このパラメーターのドキュメントブロックのドキュメント。
                • doc => FileFunctionDetailedDoc (doc). 関数の詳細ドキュメント。
                • see => FileFunctionSee (doc). 関数の「関連項目」ドキュメント。
                • return => FileFunctionReturn (doc). 関数の戻り値に関するドキュメント。
              • kind => FileFunctionKind (string). 関数の種別（通常は「function」）。
              • name => FileFunctionName (string). 関数の名前。
              • type => FileFunctionType (string). 関数によって返されるデータ型。
              • static => FileFunctionStatic (string). 関数が静的であるかどうか。
        • name => FileName (string). ファイルの名前。
        • variables => FileVariables (hash). ファイル内の変数に関する情報。
          • members => FileVariableList (list). 変数のリスト。
            • FileVariable (hash). 変数。
              • protection => FileVariableProtection (string). 変数の保護レベル。
              • detailed => FileVariableDetailed (hash). 変数に関する詳細情報。
                • doc => FileVariableDetailedDoc (doc). 変数の詳細ドキュメント。
                • see => FileVariableSee (doc). 変数の「関連項目」ドキュメント。
              • kind => FileVariableKind (string). 変数の種別（通常は「variable」）。
              • name => FileVariableName (string). 変数の名前。
              • type => FileVariableType (string). 変数のデータ型。
        • typedefs => FileTypedefs (hash). ファイル内のtypedefに関する情報。
          • members => FileTypedefList (list). typedefのリスト。
            • FileTypedef (hash). typedef。
              • protection => FileTypedefProtection (string). typedefの保護レベル。
              • detailed => FileTypedefDetailed (hash). typedefに関する詳細情報。
                • doc => FileTypedefDetailedDoc (doc). typedefの詳細ドキュメント。
                • see => FileTypedefSee (doc). typedefの「関連項目」ドキュメント。
              • kind => FileTypedefKind (string). typedefの種別（通常は「typedef」）。
              • name => FileTypedefName (string). typedefの名前。
              • type => FileTypedefType (string). typedefのデータ型。

次のセクションへ進むか、インデックスに戻る。