11

私は、ゲーム Bitfighter (http://bitfighter.org) 用の新しく拡張された Lua API の文書化に取り組んでいます。私たちの Lua オブジェクト モデルは C++ オブジェクト モデルのサブセットであり、文書化する必要がある Lua に公開されているメソッドは、C++ で使用可能なメソッドのサブセットです。Lua に関連する項目のみを文書化し、残りは無視したいと思います。

たとえば、オブジェクト BfObject はすべての Lua オブジェクトのルートですが、それ自体は C++ オブジェクト ツリーの中間にあります。BfObject には約 40 個の C++ メソッドがあり、そのうち約 10 個が Lua スクリプト作成者に関連しています。ドキュメントで BfObject をルート オブジェクトとして表示し、関連する 10 個のメソッドのみを表示したいと考えています。メソッドの継承を明確にする方法で、その子オブジェクトを表示する必要もあります。

今のところ、すべてのコードが C++ で書かれていると仮定できます。

1 つのアイデアは、doxygen などのシステムが何を見ればよいかを認識し、残りを無視するような方法で、文書化したいオブジェクトにマークを付けるというものです。もう 1 つの方法は、関係のないビットをすべて削除するような方法で C++ コードを前処理し、doxygen のようなもので残っているものを文書化することです。(実際、luadoc を使用してこのアプローチをかなり進めましたが、luadoc にオブジェクト階層を表示させる方法を見つけることができませんでした。)

役立つかもしれないことの 1 つは、すべての Lua オブジェクト クラスがその親クラスと共に一貫した方法で登録されることです。

スクリプトに Lua を使用するゲームの数は増え続けており、その多くには適切なドキュメントが用意されています。誰かがそれを作成する方法について良い提案をしていますか?

PS明確にするために、私は仕事をするツールを喜んで使用します-doxygenとluadocは、私がある程度慣れている例にすぎません。

4

3 に答える 3

2

理想的ではありませんが、かなりうまく機能する解決策を見つけました。私は、すべての Bitfighter ソース コードをリッピングし、必要な要素だけを含む「偽の」ソースの 2 番目のセットを生成する Perl スクリプトをまとめました。次に、この 2 次ソースを Doxygen で実行すると、探しているものの 95% の結果が得られます。

勝利を宣言しています。

このアプローチの利点の 1 つは、コードを "自然な" 方法で文書化できることです。スクリプトは、コード構造からそれを理解するのに十分スマートです。

興味のある方は、 https: //code.google.com/p/bitfighter/source/browse/luadoc.pl の Bitfighter ソース アーカイブで Perl スクリプトを入手できます。完成度は 80% ほどに過ぎず、非常に重要な項目 (関数の引数を適切に表示するなど) がいくつか欠けていますが、構造はあり、プロセスが機能することに満足しています。スクリプトは時間の経過とともに改善されます。

プロセスの (非常に予備的な) 結果はhttp://bitfighter.org/luadocs/index.htmlで見ることができます。テンプレートはほとんど変更されていないため、非常に「ストック」された外観になっていますが、多かれ少なかれ機能していることがわかります。

一部のコメンターは、Doxygen で適切なドキュメントを生成することは不可能であると示唆しているため、インライン ドキュメントはまだほとんど追加されていないことに注意してください。それらがどのように見えるかを理解するには、Teleporter クラスを参照してください。とても良いとは言えませんが、Doxygen が常に役に立たないドキュメントを作成するという考えを否定していると思います。

この時点での私の大きな後悔は、私の解決策が実際には 1 回限りのものであり、コミュニティでのニーズが高まっていると私が考えるものに対応していないことです。おそらくある時点で、C++ と Lua をマージする方法を標準化し、一般化されたドキュメント ツールを作成するタスクがより管理しやすくなるでしょう。

PS 元のソース ファイルのマークアップがどのように見えるかを確認できます... https://code.google.com/p/bitfighter/source/browse/zap/teleporter.cppを参照し、@luaclass を検索してください

于 2012-09-13T13:41:00.937 に答える
1

C++ コードの名前空間 (クラスの場合もあります) で除外しますが、lua コードは除外しません。

EXCLUDE_SYMBOLS = myhier_cpp::*

doxygen構成ファイルで、またはチェリーを使用して除外するものを選択します

/// @cond
class aaa {
  ...
  ...
}

/// @endcond

あなたのC++コードで。

名前空間による分離は、コードとドキュメントの分離を反映しているため、個人的には良いと思います。これにより、純粋な c++ を lua バインディングから分離するための名前空間ベースのスキームにつながります。

除外による分離は、おそらく最もターゲットを絞ったアプローチですが、コードを解析し、関連する lua 部分をマークアップし、コードに除外を追加するための追加のツールが必要になります。(さらに、このマークアップを使用して、グラフなどの特別な情報を個別にレンダリングし、イメージを介してドキュメントに追加することもできます。少なくとも、Doxygen を使用すると簡単に実行できます。) lua コードの何らかの表示が必要なので、マークアップを導出するのはおそらくそれほど難しくありません。

于 2012-09-12T12:53:41.020 に答える