Ldocを使用してLuaにドキュメントを生成
4346 ワード
Ldocの紹介
LDocはLuaのドキュメント生成ツールであり、過去によく使われていたLuaのドキュメント生成ツールはLuaDocであったが、残念ながら著者は2008年以降新しいバージョンを発表しておらず、著者が基本的にメンテナンスを放棄していることを示している.LDocはずっと更新中なので、今LDocを選んでLuaにドキュメントを生成するのがもっと良い選択です.LDocのGithubホームページです.
LDocの1つの利点は、LuaDocと互換性がありLuaDocの機能を拡張するために作られているため、LuaDocが使用できるラベルLDocも使用できることである.LDocには他にもLuaDocが備えていない利点があります.例えば LDocはMarkdown形式の文書を生成することができる. LDocで生成されたドキュメントもより美しいなど. その論理はluaコードによって記述され、ソースコード を自分で修正し理解するのに便利である.
LDocは、あるluaファイルに対して文書を生成することができるが、configを介してより推奨される.ldは、config.ldが存在するドキュメントはldocを用いる.設定したフォルダに対してドキュメントを生成できます.
Ldocインストール
Ldocが唯一依存しているライブラリはPenlightであり、PenLightはLuaFileSystemに依存しており、これらのライブラリはLuaForWindowsにすでに存在しています.LDocはluarocksから直接インストールできます.
luarocksの公式サイトにインストールする方法(Installing LuaRocks in a Unix system:):
wget、Macの下には持参していないので、brewを使ってインストールすることができます.brewも付属していません.そのインストールはHereを参照してください.
Ldoc使用
まずconfigを構成する必要がありますldファイルは私たちのプロジェクトを説明し、今回のプレゼンテーションではtestLDocという名前のプロジェクトを作成しました.config.ldの内容は以下の通りである.
Project='testLDoc'title='LDocをテストするプロジェクト'description='LDocをテストするプロジェクト'file='.'
このファイルでは、fileという意味は、ドキュメントのソースファイルを生成する場所であり、ファイルディレクトリである必要があります.このディレクトリを追加すると、下の図のsub.submoduleはサブディレクトリの下にあるモジュールであり、ドキュメントにも表示されます.プロジェクト名を追加すると、次のように生成されます.
簡単に使用し、インストール構成が完了する直接:
コメントを書いたTable、Function、およびExported Functionなどについて、Ldocは完璧な解析を行うことができます.また、形式の美しいドキュメントを生成します.具体的な効果はHereを参照してください.以下のような複雑な関数であってもldocは完全な解析を行うことができる.
このコードでは、実際に関数には2つの戻り値があることがわかります.この2つの戻り値をそれぞれ説明し、usageラベルで使用例を説明することができます.上の関数のドキュメントスタイルは次のとおりです.
LDocのラベル
上記の説明から,LDocで非常に使いやすい点は,あるパラメータのタイプを識別できることであることが分かったが,LDocはいったいどのタイプをサポートしているのだろうか.リストで説明できます.
string number int bool func識別子「function」tab識別子「table」thread識別子「coroutine」
また、tparamとtreturnでカスタムタイプを規定することもできます.いくつかのタイプがサポートされています.Personは既知のタイプ(一般的にはluaのテーブル){string,num}既知のタイプのlist{Person,...}Personの配列{[string]=Person,...}固定タイプのキー値ペアを記録するmap
テキストの最初のリンクhttp://jeffjade.com/2015/05/17/2015-05-17-lua-ldoc/
リファレンスリンクAリファレンスリンクBリファレンスリンクC
LDocはLuaのドキュメント生成ツールであり、過去によく使われていたLuaのドキュメント生成ツールはLuaDocであったが、残念ながら著者は2008年以降新しいバージョンを発表しておらず、著者が基本的にメンテナンスを放棄していることを示している.LDocはずっと更新中なので、今LDocを選んでLuaにドキュメントを生成するのがもっと良い選択です.LDocのGithubホームページです.
LDocの1つの利点は、LuaDocと互換性がありLuaDocの機能を拡張するために作られているため、LuaDocが使用できるラベルLDocも使用できることである.LDocには他にもLuaDocが備えていない利点があります.例えば
LDocは、あるluaファイルに対して文書を生成することができるが、configを介してより推奨される.ldは、config.ldが存在するドキュメントはldocを用いる.設定したフォルダに対してドキュメントを生成できます.
Ldocインストール
Ldocが唯一依存しているライブラリはPenlightであり、PenLightはLuaFileSystemに依存しており、これらのライブラリはLuaForWindowsにすでに存在しています.LDocはluarocksから直接インストールできます.
luarocks install Ldoc -v
luarocks
はD.H.Qの腐ったペン先のこの文章Luaのモジュールのインストールと配置ツール-LuaRocksを参照することができます.詳しくは、LuaRocksの機能についても触れられます.Macの下にluarocks
を取り付けるにはbrewを直接使うことができます(もちろん成功しない可能性もありますが、Brewにluarocksが内蔵されていなければ):brew install luarocks -v
luarocksの公式サイトにインストールする方法(Installing LuaRocks in a Unix system:):
wget http://luarocks.org/releases/luarocks-2.2.1.tar.gz
tar zxpf luarocks-2.2.1.tar.gz
cd luarocks-2.2.1
./configure; sudo make bootstrap
sudo luarocks install luasocket
wget、Macの下には持参していないので、brewを使ってインストールすることができます.brewも付属していません.そのインストールはHereを参照してください.
Ldoc使用
まずconfigを構成する必要がありますldファイルは私たちのプロジェクトを説明し、今回のプレゼンテーションではtestLDocという名前のプロジェクトを作成しました.config.ldの内容は以下の通りである.
Project='testLDoc'title='LDocをテストするプロジェクト'description='LDocをテストするプロジェクト'file='.'
このファイルでは、fileという意味は、ドキュメントのソースファイルを生成する場所であり、ファイルディレクトリである必要があります.このディレクトリを追加すると、下の図のsub.submoduleはサブディレクトリの下にあるモジュールであり、ドキュメントにも表示されます.プロジェクト名を追加すると、次のように生成されます.
簡単に使用し、インストール構成が完了する直接:
ldoc -v xxx
config.ld同ディレクトリの下にdocフォルダを生成し、内部にindexがある.htmlを開くと生成されたドキュメントが表示されます.コメントを書いたTable、Function、およびExported Functionなどについて、Ldocは完璧な解析を行うことができます.また、形式の美しいドキュメントを生成します.具体的な効果はHereを参照してください.以下のような複雑な関数であってもldocは完全な解析を行うことができる.
---
-- @number a first coeff
-- @number b second coeff
-- @number c third coeff
-- @return first root, or nil
-- @return second root, or imaginary root error
-- @usage local r1, r2 = solve(1, 2, 3)
function solve (a,b,c)
local disc = b^2 - 4*a*c
if disc < 0 then
return nil,"imaginary roots"
else
disc = math.sqrt(disc)
return (-b + disc)/2*a,
(-b - disc)/2*a
end
end
このコードでは、実際に関数には2つの戻り値があることがわかります.この2つの戻り値をそれぞれ説明し、usageラベルで使用例を説明することができます.上の関数のドキュメントスタイルは次のとおりです.
LDocのラベル
上記の説明から,LDocで非常に使いやすい点は,あるパラメータのタイプを識別できることであることが分かったが,LDocはいったいどのタイプをサポートしているのだろうか.リストで説明できます.
string number int bool func識別子「function」tab識別子「table」thread識別子「coroutine」
また、tparamとtreturnでカスタムタイプを規定することもできます.いくつかのタイプがサポートされています.Personは既知のタイプ(一般的にはluaのテーブル){string,num}既知のタイプのlist{Person,...}Personの配列{[string]=Person,...}固定タイプのキー値ペアを記録するmap
テキストの最初のリンクhttp://jeffjade.com/2015/05/17/2015-05-17-lua-ldoc/
リファレンスリンクAリファレンスリンクBリファレンスリンクC