Re: Lua at ONLamp - POD for documenting Lua modules

[hisham.hm@...]

On 7/21/07, David Manura <dm.lua@math2.org> 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,
dependencies,
> > 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 <yuri@sims.berkeley.edu> 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, http://www.php.net/sort ) -- 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
documentation).

-- Hisham