Documenting Lua
From GMod Wiki
Contents |
Creating Documentation for Lua
Being able to write great Lua doesn't just mean being able to write well. In team projects and collaboration projects, and even projects that are for release, documenting your code is important.
In this guide i'll be showing you how to use Natural Docs, which produces excellent documentation for any language. A small amount of configuration is needed to make ND work well with Lua, but once it's set up you can have it automatically generate docs for you.
I'll assume you have a webserver running Linux set up, though for Windows this should be similar.
Installing Natural Docs
ND requires Perl; on Linux you'll probably have this, but for Windows you'll need something like ActivePerl.
Download ND's latest release here.
Install and run with the following line:
/home/nd/NaturalDocs -i /tmp/workdir_mrpm -o HTML /home/nd/public_html/melonrpm/ -p /home/nd/melonrpm/
Obviously you'll have to modify your paths a bit.
The path after -i is the input folder. Everything here gets looked at.
After -o is the type of output- HTML- and where it wants to get placed.
After -p is the project directory for NaturalDocs to store it's content in.
Run the script- no docs will be produced but ND will set up a config folder for you.
Configuring Natural Docs to read Lua
Look in the project folder:
[nd@intrepid ~]$ ls melonrpm Data Languages.txt Menu.txt Topics.txt
Languages.txt has the info for languages. Open it up, and add this to the bottom;
Language: Lua Extension: lua Line Comment: -- // Block Comment: --[[ ]] /* */ Function Prototype Ender: \n Variable Prototype Enders: ; =
Once you've added this, Natural Docs will look for the Lua files.
Natural Docs does not support fully automatic Lua documentation, so you have to tell it what to document in your source.
Extending your runscript
If you have a SVN repository on Google Code or GModForge, you can modify your runline to automatically grab the latest code and document it.
rm -rf /tmp/workdir_mrpm svn export https://www.gmodforge.com/svn/melonrpm/gamemode/ /tmp/workdir_mrpm /home/nd/NaturalDocs -i /tmp/workdir_mrpm -o HTML /home/nd/public_html/melonrpm/ -p /home/nd/melonrpm/
Again, modify paths- /tmp/workdir_mrpm can be any directory to hold the files temporarily, and your SVN URL will vary.
Documenting your Code
Natural Docs is so called because it's a very natural way of writing it. It's easy to read in the source code as well as on the documentation site.
Here's an example of some documentation for a function. Unfortunately as i've used long-style Lua comments here and Garry decided to filter those to be //, it's not highlighted, but you get the idea.
--[[
Function: MRPM.Query
SQL query function. Runs a query.
Parameters:
qstring - Query to run.
Returns:
If the query fails to run, false.
If the query runs, the result table.
See Also:
<MRPM.CleanSQL>
]]
function MRPM.Query(qstring)
-- Clean up the query.
--local q = MRPM.CleanSQL(qstring);
if MRPM.Config.SQL["type"] == "mysql" then
local t,state,err = mysql.query(MRPM.SQL,qstring);
if not t then
MRPM.Log("# MySQL Error running query!\n\nQuery: "..qstring.."\nError message: "..error, 1)
return false;
end
elseif MRPM.Config.SQL["type"] == "sqlite" then
local t = sql.Query(q); -- Run the query
if not t == nil then return t else
MRPM.Log("# SQLite Error running query!\nError: "..sql.LastError().."\n\nQuery: "..qstring.."\n", 1)
return false;
end
end
return t;
end
This produces output like this.
There's a much better guide over at Natural Docs's own site, so read that to find out more.
