This site intends to provide a centralized interface for browsing Lua modules and documentation (similar to Perl's search.cpan.org). Currently, documentation for only a handfull of modules is included.
The modules can be searched above and are sorted alphabetically below by package name:
Module documentation should be formatted in the POD format for submission. For details on the POD format see perlpod. The POD documentation is rendered as HTML on this site. It is recommended that you follow the POD conventions used in the existing modules above.
To submit your POD documentation, you preferably place your project registered on LuaForge. Place your POD file inside your module's distribution (.tar.gz or .zip file) in the Files section of LuaForge for your project. Then notify me by placing a message on this site's Lua Wiki page (http://lua-users.org/wiki/LuaSearch). When I see your note, I will download/extract your POD file and upload it to this site. (Note: We may automate this more in the future. The LuaForge site indirectly acts as an authentication mechanism.)
To get this site started, I've taken the liberty myself to convert the documentation of the standard libraries, some Kepler libraries, and a few others to POD format.
Why POD? Why not doxygen? Why not Luadoc? Why not ...?
POD is simple to edit with a text editor, like a wiki syntax. See Wikipedia page on POD. It's a low burden with good return.
POD can be converted to many formats including HTML, LaTeX, PDF, WinHelp, .... There are existing tools for this. It's also fairly easy to write your own specialized converter. POD from different modules can reference each other, and these links can be preserved in the HTML or other conversion targets.
Tools like doxygen and some others parse your source code to extract the static interface. In a dynamic and multiparadigm language like Lua (in contrast to C), the interface may not be as apparent by static analysis of the source code alone. In Lua one often defines their own concepts (OO or otherwise) via tables, metatables, and functions, even at run-time as these are first class objects in Lua, and this might not be extractable by a general tool. In constrast, POD processors largely ignore your source code and even what language it is (except to extract the POD), and the POD format itself it informal and usable how you best see fit. This informality brings a flexibility, as the responsibility is on you to identify the important higher-level "concepts" to document. This may also be how it should be (for quite a few developers, doxygen-style output is not really what they want or that is most meaningful). Tools that ask to you document along the static interface may also be putting you in the wrong mind-set (in fact, literate programming inverts that). Yes, static interface is important, but a lot more qualitative characteristics need to be documented on your module besides that:
These concerns can correspond to specific sections of the POD as shown in the examples given on this page.
Some like Python-like "docstrings", which POD alone does not provide. These can be nice, if you even make use of them. However, there can often be more to document that you might want to place into docstrings or that can be associated with objects at run-time. Though POD does not provide this, you might still be able to achieve it in conjunction with POD--e.g. write some helper functions in Lua maybe.
POD was worked remarkably well for the Perl programming language. See CPAN Search. There are thousands of Perl modules and the documentation has a high level of consistency, accessibility and usefulness despite being maintained by a large number of developers working independently. If you find a Perl module, the documentaion is almost undoubtably in POD and located on CPAN. The same can not be said of most other languages (e.g. C) with more fragmented documentation. From a practical point of view, POD provides a realizable hope of bringing consistency to Lua documentation.
The recommendation is to follow by examples from the existing POD files above. See also the perlpod reference. You may want to use the pod2html command-line tool that comes with the Perl language to convert your POD to HTML (maybe someone will write an equivalent or better tool in Lua too).
POD can be placed in a separate file (conventionally with the file name extension ".pod") or inserted into Lua comments, preferable block comments:
-- mymodule.lua
module("mymodule", package.seeall)
function hello()
print("Hello world!")
end
--[[
=head1 NAME
mymodule - my module
=head1 OVERVIEW
This is my module.
=head1 REFERENCE
=head2 C<mymodule.hello>
Prints a hello message.
]]
When inserting POD into source code, many find it useful to place all the POD at the bottom (or top) of the file (some even place it in a separate file) rather than interleave it with the source code. (Interestingly, this is what Kepler and others have instead done with HTML.) Aesthetically, keeping the POD together in one place can produce a better effect even though your first thought might be to interleave it. You may still interleave regular Lua comments for documenting the implementation but leave POD for the higher-level task of documenting the interface or client-view of your module.
For any comments or questions on this page, please post it on the LuaSearch wiki page.