この記事の対象者
経験の浅いC ++開発者は、この記事で新しく興味深いものを見つけるでしょう。 最大の平凡なチーム
gcc -c -x c++ -I ./ */*/*/*/*.h
彼らはすでに知っています。
しかし、あなたが初心者開発者である場合、またはプロジェクトのドキュメントを初めて作成する場合、または一度試してみて、doxygenが生成したナンセンスを見ると、それを削除して悪い夢のように忘れて、猫にようこそ、おそらくあなたは見つけるでしょうその後、いくつかの有用な考え。
はじめに
C ++プログラミングは、主に既存のコードの分析です。
ここ数年、私はシミュレーションシステムの開発に参加しています。 開発は、ストラウストルップの偉大で強力な発案で行われます。 そして、私が言わなければならないのは、このプロジェクトは長年、C ++で書かれた独自のマクロの方言ほどではありませんでした（以下でこれが重要である理由が明らかになります）。 この状況は多くのC ++開発者によく知られていると思います。
私がこのプロジェクトの研究を始めたばかりのとき、彼らはすぐにdoxygenを使用してドキュメントを作成するようにアドバイスしました。 しかし、何らかの理由で、このツールとの友情はうまくいきませんでした。数年後、次回このツールについて思い出しました。
背景
時間の経過、私のプロフェッショナリズム（希望どおり）が成長し、プロジェクトが発展し、図書館で秩序を回復したかったのですが、それは積極的に支配されていました。 ここでの順序とは、1つのヘッダーファイル= 1つのエンティティ（またはいくつかの小さく密接に関連するもの）の概念と、すべてのファイルを3つのタイプ-ヘッダー、内部、ソース-それぞれ* .h、* .inl、* .cppに分けることを意味します。 さらに、ヘッダーファイルにはクラスの単一メンバー関数の定義がなく、それらはすべてcppファイルまたはinlファイルのいずれかであるように、分離を実行する必要があります。 さらに、すべてのモジュールコードは単一の標準に従ってフォーマットされている必要があり、最も興味深いのは、ほとんどのエンティティが特別なdoxygenコマンド（\ interface、\ class、\ todo、\ brief、\ enumなど）を使用してコメントアウトされることです。
問題
すぐに言ってやった。 数週間の殺された夜の後、非常識なタスクは完了しました！ コードは美しいので、少し涙が出ます。
そして、doxygenがシステムの私の（当時はすでに愛されていた）モジュールの説明を含む最も美しく正確なドキュメントを作成するのを待つ間、いすに座る時が来ました。 そして沈む心で
cd Project/doc
doxygen project-doxyfile
cd html/
./index.html
しかし、私に見えたのは、控えめに言ってもゴミです。 Doxygenは率直にごまかしました：ダイアグラムは不完全で、名前空間が空で、関数を提供しようとするマクロは一般にすべてを数えることができません...しかし、最初の分析では、彼はマクロ（すべての名前空間、スマートポインター（別のマクロを使用して設定されました）。
オプションのソリューションは事前定義されていますか？
最初に疑われたのは、酸素濃度の設定でした。 ENABLE_PREPROCESSING、MACRO_EXPANSION、EXPAND_ONLY_PREDEF、SEARCH_INCLUDES、INCLUDE_PATHなどのオプションが再確認されました。 しかし、設定は論理的に見え、マクロが正しく認識され始めませんでした。 その後、「なぜdoxygenが混乱するのか？」という質問には答えませんでしたが、必要なマクロを説明することができましたが、PREDEFINEDオプションが登場しました。 これはしばらくの間、問題の解決策でした。 しかし、このオプションに常に新しいマクロを追加する必要があったという事実は、非常に憂鬱であり、doxygenの研究を続けることを余儀なくされました。
問題はコードにあります！
私は長い間、doxygenの動作について考え、それをグーグルで調べました。 そして、彼はマクロを処理するのを妨げた恐ろしいバグを見つけて修正するという正しい考えで、svnでそれを自分自身に漏らしさえしました:)
しかし、やがてやめました。コンパイラとコンパイラの違いを理解したからです。 彼らはcppファイルを理解するだけでなく、ヘッダーファイルでも同じことをする必要があるため、その目標は非常に異なります（そしてDoxigenは何らかの方法でさらに複雑です）。 ファイルごと。 そして、ここで私が以前は考えなかった興味深いことがあります。コンパイラはヘッダーファイルに興味がなく、「翻訳単位」、または#includeディレクティブが既に機能しているプリプロセッサの出力を受け取ります。 このように言い換えることができます-コンパイラは、翻訳ユニットのコンテキストで、いわば間接的にのみヘッダーファイルを処理します。 そして、まさにこのコンテキストでコンパイルします。 したがって、残念な結論-ヘッダーファイル自体は間違っている可能性がありますが、その使用のコンテキストでは正しいものになり、コンパイラはそれについて何も通知しません！
ただし、doxygenでは、これは機能しません。ヘッダーファイルは、ソースコードを含むスタンドアロンの自給自足のドキュメントとして分析されます。 また、使用されるエンティティ（このヘッダーファイルを使用するコンテキストで表示される）の宣言が欠落している場合、doxygenは誤っています。 そして、私たちのプロジェクトに影響を与えたのはこの病気だった可能性が非常に高いです。
それでは、ヘッダーファイルには、コンパイラにとってとらえどころのないどのようなエラーが隠されているのでしょうか。 これは、悪名高いマクロが定義されているファイルの#includeディレクティブではありません。 つまり cppファイルをコンパイルすると、すべての定義は「問題」ヘッダーファイルではなく、何らかの迂回方法で現在の翻訳単位に分類されます。 この発見の後、私たちのチームで会議が開催され、議題に関する主な質問が「そして実際、それをどうするか？」 問題は、そのような振る舞い-すべての必要な包含物の欠如-が誤りであるという事実に賛成して解決されました。 主な引数は非常に単純です-ヘッダーファイルはどこにでもインクルードされる可能性があるため、コンパイルするのに十分なものである必要があります。
解決策は「ヘッダーファイルのコンパイル」です。
これが、「ヘッダーファイルのコンパイル」の問題が発生した場所です。
このイベントのポイントは、ソース（* .cpp）ファイルのコンテキストに追加せずにすべてのヘッダーファイルをコンパイラーで分析し、エラーを報告することです。 そして、それらが修正された場合、doxygenはすべての図などを含むプロジェクトドキュメントを適切に構築する言い訳をすべきではありません。
ここで、私たちのチームで使用されているコンパイラーについて直接話しましょう。
歴史的な理由により、これはms visual studioであり、2008年の標準です。 しかし、この話が終わる直前に、GNU / Linuxの下でシステムのコンピューティングコアを翻訳するプロジェクトは無事に完了しました。 そして当然、この環境では、GCCコンパイラバージョン4.6として選ばれました。
そして、私は要求で彼を苦しめ始めました、彼らは私に見出しを編集すると言います。 そして彼は長い間抵抗しました...彼が陥没するまで。
彼の男の思慮深い読書は私に-Iオプションを示しました。GCCで引用インレイを検索するパスを指定できます。
ここで、1つの重要な事実に注意する必要があります。このプロジェクトでは、「プロジェクトのルートからインクルージョンにファイルへのパスを示す」というルールを長い間（そして非常にうまく）遵守しました。 この規律により、単一の-Iオプションを省くことができました。
その後、すべてのプロジェクトヘッダーファイルをgcc入力に送信します。 しかし、ここでは、パイプラインを介してlsコマンドの出力を入力として受け入れることにgccが抵抗するため、いくつかのヒッチがありました。 しかし、解決策はさらに簡単であることが判明し、gccは転送されたマスクによって入力ファイルをすでに検索していました。
だからチーム
g++ -I ./ */*/*/*/*.h */*/*/*.h */*/*.h
すべてのライブラリヘッダーファイルを完全に検証します。
* .inlファイルが入力として与えられた場合、次にgccが抵抗し始めました。 オプション-c（リンクなしのコンパイルのみ）および-x c ++（プログラミング言語の明示的な設定）が役立ちました。
ヘッダー（*放置することにした.inlファイル）ファイルの検証に使用される最後のコマンド：
gcc -c -x c++ -I ./ */*/*/*/*.h */*/*/*.h */*/*.h
さて、エラーを修正してdoxygenを使用することは残っています。
そして、一般に、確かに、たとえばここでネジ留めするなど、何かを改善できますが、この投稿の主なアイデアは、doxygenの一見奇妙な動作と戦うために「ヘッダーファイルをコンパイルする」必要性です。 だから、最後の最も勤勉な読者にうんざりするまでここでやめます;）
結論の代わりに
そして実際、なぜこの投稿が「...または無料のドキュメント」と呼ばれるのか。
はい、コードにdoxygenのコメントが1行もないかもしれませんが、あらゆる種類の図を使用してドキュメントを作成できます。これは、新しいプロジェクトを検討する際に非常に役立ちます。 つまり、ドキュメントの自動構築（便利なナビゲーションと図）により、新入生（およびこれはすべて工科大学で行われる）が非常に大規模で複雑なシステムを簡単に研究できるようになるはずであり、私たちのプロジェクトでdoxygenを使用する最初の目標でした。
当然、コメントでは、建設的な批判、修正、適度に曲がったチームの追加、および質問を楽しみにしています。