Re: [ANN] LuaDoc 3.0 Released

[Ross Berteig <Ross@...>]

On 8/13/2007, Tomas Guisasola Gorham wrote:
> LuaDoc is a documentation generator tool for Lua source code.
> It parses the declarations and documentation comments in a set 
> of Lua source
> files and produces a set of XHTML pages describing the 
> commented declarations
> and functions...

I downloaded and installed from the CVS HEAD having noticed that 
there have been several minor issues documented and corrected 
since the 3.0 release... and tripped over a couple of minor 
issues with luadoc on Windows. I decided to report them formally 
on the bug tracker at luaforge, but thought I would mention them 
to the list at large for redundancy.

1. My windows box has no C: drive.  Its a long story, but I use 
E: as the boot drive and usually never have a disk mounted at 
C:, and often find bugs where someone assumed that every Windows 
box has a C: drive.  The Windows makefile is easily customized 
to point to my preference, but luadoc.bat contains a hard-coded 
pathname to luadoc_start.lua that is not customized.  I resolved 
this for myself by having Makefile.win write luadoc.bat based on 
the customized macros using an ECHO command.

2. In windows, some combination of LFS and the command line 
handling causes the path names to parsed files to get a 
mish-mash of \ and / characters, but the code that figures out 
how to refere to the style sheet seems to only count / 
characters. I patched .../taglet/standard.lua in the function 
directory(path,doc) to fold all slashes to forward-slash. There 
may be a "better" place to fix it, but this worked for me.  This 
is a classic Windows vs. Unix issue, where the Unix notation 
works fine, but running in Windows will have the effect of 
getting the other separator in play from time to time.

As a big believer in Doxygen, I look forward to using luadoc to 
improve the quality the internal documentation of my lua-based 
projects.  I may be investigating ways to integrate the C side 
documentation handled by Doxygen with the Lua side handled by 
luadoc... especially if a good way can be found to integrate the 
lua-callable point of view with the C source to a C module.

Ross Berteig                               Ross@CheshireEng.com
Cheshire Engineering Corp.           http://www.CheshireEng.com/