RE: [ANNOUNCE] Improvements to stdlib (wiki: StandardLibraries)

[Nick Trout <Nick.Trout@...>]

> > I put a document generator in Doris (selfdoc.lua in 
> doris/src). I'm trying
> > to document version 0.5 for release fairly soon. It 
> "inverts" the code thats
> > commented "--!" and executes it to generate the docs. It 
> also generates an
> > index, has groups, nice fomatting :-) . May be useful?
> 
> It certainly looks interesting. I'd be interested to hear 
> other people's 
> opinions, as I've not used *Doc systems much.

I've used Doxygen, which I think is great, does everything you need. I
looked into writing a parser or convertor for Doxygen but too much hassle
(ie. quicker to just write on in Lua) and formatting not quite right for
Lua. I think you just need simple groups and items in groups for Lua docs as
Lua usage is pretty open ended.

I put up an example of the output:
http://lua-users.org/files/wiki_insecure/users/ntrout/doris.html

> This one is > flexible, and 
> makes good use of Lua's lightweight string/table syntax, but 
> I'm wondering > if it's too flexible (i.e. confusing)

Ah. I set out to add "formatters" so that you could render your document in
HTML, Latex, PS etc. But as always, time ran out and I only need HTML. So it
could probably be simplified significantly, unless people want other
formats. Actually, selfdoc got its name because I was going to include the
document generator with doris. ie. you do "doris -html -doc all" and it
generates a set of docs in the appropriate format. I dont think the docs
included would have occupied that much space, and if something like upx is
used there would only be slight bloat. I suppose the idea is that doris is a
self contained app, you dont need any libraries etc so it can be distributed
stand alone. I decided against this because you really want to distibute
examples with your app, which may also come with data. I guess it could be
adapted to be used either way.

> and whether the syntax is 
> lightweight enough to be reasonably easy to read in an editor.

To save a parsing all the docs are in Lua code. An added advantage of this
might be that you can auto generate docs run from script when the docs are
generated. Not sure how often you'd do this but it might be useful for
including example code. The Lua bit could be substituted for tags, as you
have done but then you have to parse - horses for courses - might be easier
on the eye?

> I can certainly see myself being convinced. I think the main thing it 
> would take is a very simple (and reasonably strict) set of "tags".

"group", "item", "params", "returns", seems to work

> >From the look of your CVS tree you've also looked at and 
> discarded LuaDoc.

I did use it and then development seems to have stopped. I didnt really like
the formatting to be honest, having to included regexp strings, and output
was a little basic.