地殻モンスターを作成するときは、文書化する

ウラジミール・フィロノフの素晴らしい写真から取られたこの格言ミームの下で、少なくともプログラミングと遠い関係にあるすべての人が彼の署名をするでしょう。 質問全体はどうですか？ 何かを正確に文書化するには？

以下のテキストにはいくつかの目的があります。

1. C / C ++の世界のchthonicモンスターに適用可能なツールの不満足な状態の概要を読んでください（トピックを少し調整してください）;
2. 代替ソリューションを提供します（無料、SMSおよび登録なし-プロジェクトは非営利であり、MITライセンスの下でGitHubに投稿されます）。
3. トピックについてコミュニケーションを取り、アイデアを収集するようにコミュニティを奨励します。
4. GitHubでプロジェクトの開発に参加してください。

このプロジェクトは主に代替として、またはsyshlとAPIのDoxygenアドオンとして主に作成されましたが、アーキテクチャ的には他の言語にも等しく適しているとすぐに言わなければなりません。 これにより、さまざまなライブラリのドキュメントポータルを作成できます。ライブラリ自体は異なる言語で記述でき、ドキュメントの外観と動作は統一されたスタイルになります。

やる気

概して、APIとライブラリのドキュメント化には、肯定的かそうでないかの2つのアプローチがあります。

• 最初はペンですべてを書くことです。

ヘルプとマニュアル、RoboHelp、Word、または別のエディターで-それは何でも構いません。 この伝統的な方法は誰にでも明らかであり、まだ広く使用されているという事実にもかかわらず、私はそれが根本的に間違っていると深く確信しています。 実際には、ドキュメントを生成しますが、これは常に場所では無関係であり、ドキュメントオブジェクトよりも遅れています 。 別々に作成され、多くの場合異なる人々、ドキュメント、絶えず進化しているライブラリAPI間の一貫性を維持します-死んだまたは冷凍された食品のみが進化しません -これは巨大なタスクであり、主要なドキュメントを書くのは少し簡単です。

• 2つ目の「正しい」アプローチは、ソースドキュメントを自動的に生成することです。

特別に訓練されたパーサーがソースを実行し、特別な形式のコメントをドキュメントで分離し、API公示ツリーの構造を構築します。 その後、ドキュメントは必要な形式で生成されます。私は、大半の人が主にHTMLとPDFに興味があると信じています。 このアプローチの主な利点は、APIのソースコードと最終ドキュメントの宣言の一貫性が保証されていることです。 実際の「ドキュメント」に意味のあるコメントがソースコードに完全に存在しない場合でも、最終的には、宣言や型の説明などを「ジャンプ」する機能を備えたAPIライブラリの状態の優れたスナップショットが得られます 。

それで、あなたの許可を得て、自動生成の「正しい」アプローチに集中します。 ここにはどのようなオプションがありますか？ 悲しいかな、現時点ではC / C ++のドキュメンテーションのために、 DoxygenとQDocがあり、実際にはほとんど使用されていません 。 そして、これら2つでも、すべてが順調に進んでいるとは言えません。

Doxygenは、プロのコードからコメントを抽出し、ハイパーリンク、継承グラフの画像、呼び出しなどを含むHTMLドキュメントに変換する最初の本当に成功したプロジェクトです。 直接の親であるDoc ++の先駆者であり、十分な配布を受けたことがないDoxygenは、C / C ++コードを文書化するための事実上の標準になりました 。 そして、これらの2つがなければ、これはすべて素晴らしいでしょう：

• doxigenが生成する標準のHTMLは、控えめに言っても... 優雅さを備えていません 。

もちろん、主観主義の場所もあります。 私は、毒素排出に完全に満足しているそれほどうるさい人が世界にいないことを完全に認めています（しかし、私は彼らの中にプロのデザイナーはいないだろうと思います）。 しかし、デフォルトのDoxigenic HTMLが視覚の観点から誰かに合っていても（そして、真剣に、 美的に本当に好きな人がいますか？コメントを書いてください！）、非常に頻繁にCSSのねじれを超えたものを変更して構成したい-たとえば、この特定のライブラリで受け入れられているコーディングスタイルに従って、 <pre>に広告を配置し、インデントとスペースを配置します。 これにより、Doxygenの2番目の、より根本的な問題が発生します。

• Doxygenは長寿命であるため、実際のモジュール式のカスタマイズ性は向上していません。

はい、たくさんの変数を持つDoxyfileがあります。HTMLヘッダーとCSSを変更することは可能ですが、アーキテクチャ的にはすべてがモノリシックC ++カーネルにハードコーディングされています。 さらに、フロントエンド、つまりソースパーサーとバックエンド（HTML、PDF、RTF、およびその他のジェネレーター）の両方がハードコーディングされています（その中には、XMLがあります）。

QDocはデフォルトで、DoxygenよりもはるかにきれいなHTMLを生成します。 残念ながら、 デフォルトではなく何かが必要な場合 、QDocはDoxygenと同じ生まれつきの木製性に悩まされます （もちろん、同じ まあ... パーサーとジェネレーターの両方の硬度をモノリシックプラスコアにします）。 Doxygenとは異なり、QDocには木製性に加えて、C ++のQT方言用の入力パーサーが1つしかありません （すべてのQ_OBJECT 、 Q_PROPERTY 、 foreachなどがキーワードとしてハードコードされています）。 そして同時に-絶対にゲートではない-PDFを生成できません！

代替案

1つのツールをコンベアに置き換えることが提案されています。 代わりに

 Doxygen -> (HTML, PDF, ...) 

...次のパイプラインを使用します。

 Doxygen -> (XML) -> -> - -> (reStructuredText) -> -> Sphinx -> (HTML, PDF, ...) 

私たちは古いものを残していますか？

開発者は、 Doxygenコメントを使用してC / C ++コードをドキュメント化する方法を知っており、慣れています ：

 /*! \brief This is a brief documentation for class Foo. This is a detailed documentation for class Foo. ... */ class Foo { // ... } 

なぜ新しい構文を発明するのですか？ 以前と同じ方法でドキュメントを書きます！

Doxygenは、ソースからドキュメントを取得し、XMLデータベースの宣言ツリーと一緒にまとめることができます。 いいね！ これがフロントエンドになります。

バックエンドとして何を使用するかという質問に答えるのは簡単です-もちろん、 スフィンクスです。 Sphinxは、技術文書を作成するためのツールとして、膨大な量のディストリビューションに値するものでした。 CSSだけでなく、本格的なテーマをサポートする非常に美味なHTMLを生成します。すべてを1つのHTMLシートに接着し、PDF、EPUB、および他の多くの形式のドキュメントを生成できます。 しかし、最も重要なのは、Pythonスクリプトの助けを借りて完全にカスタマイズ可能であり、外観の調整と入力言語（reStructuredTextはSphinxの場合）の拡張の両方に使用できることです。つまり、独自のディレクティブを追加してドキュメントで使用できます。

DoxygenとSphinxを友達にすることは残っています。

橋を架ける

DoxygenとSphinxの間に橋を架けようとするのは私が最初ではないことに注意してください。 Sphinxの拡張機能としてPythonで記述されたbreathプロジェクトは、比較的有名になりました。 現時点では、プロジェクトはドライバーであまり積極的にピッキングしておらず、悲しいことに、箱から出してすぐに深刻なタスクに適していません。 アーキテクチャ的には、次のように構成されています。DoxigenXML出力を解析し、メモリ内のツリーのreStructuredTextノードを直接作成します。

私は少し違う方法で行くことにしました。 Doxyrest-これはブリッジの名前です-Doxigen .xmlファイルを解析し、解析されたXMLと一連のテンプレートファイルをテンプレートエンジン （文字列テンプレートエンジン、テンプレートプロセッサ）に送信します。 テンプレートエンジンはreStructuredTextを使用してファイルを生成します。これらの.rstファイルは既にSphinx-back-endに転送され、指定された形式の最終ドキュメントを取得します。

もちろん、主な機能はテンプレートエンジンの使用です。 これにより、ドキュメントの構造を完全にカスタマイズできます ：順序の変更とドキュメント化されたオブジェクト（クラス/関数/プロパティなど）のグループ化、宣言のスタイル（インデント、スペース、改行などの使用場所と方法）のカスタマイズ、任意のロジックの使用ドキュメントにこの特定のオブジェクトを含めるか含めないかの難しさ-そして、これらすべてを再コンパイルせずに 、入力テンプレートを編集するだけです！

しかし、主なもの-テンプレートエンジンを使用するアプローチにより、Doxyrestを他のほとんどの言語 、特にさまざまなDSLに適用することができます-誰も特別なドキュメントシステムを作成することはありません。 Doxygenは言語を解析できませんか？ 言語コンパイラを使用し、既存のASTからDoxygenのようなXMLの生成を追加し、出力.rstファイルテンプレートを修正しました-ドキュメントの宣言が必要な構文であるように-そしてそれです！ Doxygenコメントを使用して言語をドキュメント化し、出力として美しいSphinxドキュメントを取得できるようになりました。

現在、 Lua言語はテンプレート化に使用されています（単に、既製でデバッグ済みのLua文字列テンプレートライブラリがすでにあるためです）が、理論的には、他のテンプレート言語のサポートの追加を妨げるものはありません。

テンプレートは次のように見え、機能します。

  Title ===== %{ if false then } This text will be excluded.. %{ end -- if for i = 1, 3 do } * List item $i %{ end -- for } 

出力には次のものがあります。

  Title ===== * List item 1 * List item 2 * List item 3 

使用例

百回聞くよりも一度見たほうがいい。 したがって、結論を出す代わりに、さまざまな言語に適用されるDoxyrestの作業の結果へのリンクを単に提供することにしました。

• Jancy Standard Library Reference （ジャンシー言語）
• Jancy C APIリファレンス （C言語）
• IO Ninja APIリファレンス （ジャンシー言語）
• AXLライブラリリファレンス （C ++）

上記のリンクのドキュメントの内容（クラス、関数などの実際の説明）が不完全であっても、メソッドの操作性を実証するにはこれで十分です。

GitHubプロジェクトページ： http : //github.com/vovkos/doxyrest

このプロジェクトは、世界で最も厳格ではないライセンスの1つであるMITライセンスの下で設計されています。 開発に参加してみてください。 そして、私はコメントのすべての質問に答えさせていただきます。