lua2dox Documentation

Introduction

A hack lua2dox converter Version 0.2

This lets us make Doxygen output some documentation to let us develop this code.

It is partially cribbed from the functionality of lua2dox (http://search.cpan.org/~alec/Doxygen-Lua-0.02/lib/Doxygen/Lua.pm). Found on CPAN when looking for something else; kinda handy.

Improved from lua2dox to make the doxygen output more friendly. Also it runs faster in lua rather than Perl.

Because this Perl based system is called "lua2dox"., I have decided to add ".lua" to the name to keep the two separate.

Running

1. Ensure doxygen is installed on your system and that you are familiar with its use. Best is to try to make and document some simple C/C++/PHP to see what it produces. You can experiment with the enclosed example code.

2. Run "doxygen -g" to create a default Doxyfile.

   Then alter it to let it recognise lua. Add the two following lines:

   FILE_PATTERNS   = *.lua
   
   FILTER_PATTERNS = *.lua=lua2dox_filter

   Either add them to the end or find the appropriate entry in Doxyfile.

   There are other lines that you might like to alter, but see futher documentation for details.

3. When Doxyfile is edited run "doxygen"

   The core function reads the input file (filename or stdin) and outputs some pseudo C-ish language. It only has to be good enough for doxygen to see it as legal. Therefore our lua interpreter is fairly limited, but "good enough".

   One limitation is that each line is treated separately (except for long comments). The implication is that class and function declarations must be on the same line. Some functions can have their parameter lists extended over multiple lines to make it look neat. Managing this where there are also some comments is a bit more coding than I want to do at this stage, so it will probably not document accurately if we do do this.

   However I have put in a hack that will insert the "missing" close paren. The effect is that you will get the function documented, but not with the parameter list you might expect.

Installation

Here for linux or unix-like, for any other OS you need to refer to other documentation.

This file is "lua2dox.lua". It gets called by "lua2dox_filter"(bash). Somewhere in your path (e.g. "~/bin" or "/usr/local/bin") put a link to "lua2dox_filter".

Documentation

Read the external documentation that should be part of this package. For example look for the "README" and some .PDFs.