[Date Prev][Date Next][Thread Prev][Thread Next]
- Subject: Re: Lua at ONLamp - POD for documenting Lua modules
- From: hisham.hm@...
- Date: Mon, 23 Jul 2007 00:28:34 -0300
On 7/21/07, David Manura <email@example.com> 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
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
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 <firstname.lastname@example.org> 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