lua-users home
lua-l archive

[Date Prev][Date Next][Thread Prev][Thread Next] [Date Index] [Thread Index]

On 7/21/07, David Manura <> wrote:

I think a distinction needs to be made between two or three types of
module documentation.  One is the (typically static) API--e.g. the function
signatures and their meaning.  The second is a more conceptual
description of the
module in context--it's purpose, examples, and the logical concepts
the module
deals with (e.g. a module that provides an API for regular
expression matching may
also describe conceptually what is a regular expression, as well as
its syntax
and common usages).  Third, there are the more administrative items such as
credits, license, contacting the author, limitations/known bugs,
project URL, compatibility, etc.

Agreed. After posting my message I thought about "two kinds of
documentation" to, in terms of reference vs. tutorial, a bit like
Reference Manual vs. PIL, and how LuaDoc, like you said, is oriented
towards one type but not the other. For the reference material, I
think docs embedded in the source are the way to go. But yes, they
alone are not sufficient (as it shows in the LuaRocks project, where
we're using a wiki for the rest).

On 7/22/07, Yuri Takhteyev <> wrote:
One possibility is to set up a site running Sputnik which would offer:

1. A POD-formatted summary at the minimum
2. Full POD documentation, editable as a wiki page, if available
3. LuaDOC-generated code if the code has LuaDOC comments.
4. A rockspec if the package is available as a LuaRock
5. Perhaps return the actual source for simple modules.

That's a nice direction for a Lua modules repository website. While
we're brainstorming ideas, another thing I've always found nice is the
"User Contributed Notes" section on every page of the PHP manual (for
example, ) -- in my experience, this increases
the value of the documentation manyfold. (And it's not the same as
making the docs wiki-editable, as they are more like side notes to the

-- Hisham