Documentation generator and refactoring

In order to move forward with lubyk project and announce some nice tools that we created for a recent show, we need to start writing some good documentation and cleanup some code.

Documentation generator

The specifications for the documentation tool were:

• Generate documentation from source code.
• Support literate programing for tutorial style source files.
• Support latex math.
• Parse function names even if there is no comment.
• Produce documentation in the same order as the content of the source file (with sub-titles, sections, etc).
• Good navigation support across classes, functions and modules.
• Parse any lua file (does not depend on naming conventions) and create simple to link html pages.

After playing with a simple state machine to parse lua code, some real world documentation and many improvements, the generator is finished and works fine with source files adapted for it.

All documentation for lubyk now lives at:

Lubyk documentation: doc.lubyk.org

Some well documented files include test.Suite, lk.Doc and part of the upcoming graphics and geometry library “lug”: lug.V2.

All documentation is generated with lk.Doc by parsing the sources.

Refactoring

To avoid complex inter-modules dependencies and weird surprises in the long run, we are splitting “lk” into several modules and creating a core graphics and geometry compatibility module to hold things like vectors, buffers and such. Here are the new modules with their purpose:

lub

lub = lubyk base

This will be the core library. The one dealing with low level scheduling, threads, package management and memory. It replaces “lk”.

Important things that should go in “lub” :

• Scheduler (should not depend on zmq)
• Doc
• Test
• Timer
• Thread
• TimeRef
• Finalizer
• C++ only:
  • Fifo
  • Mutex
  • msgpack

As “Doc” and “Test” would depend on lubyk utilities and filesystem, we need to have those in “lub” too. The idea is that lub depends on nothing else (remove lfs dependency if possible).

So “lub” also contains:

Lubyk filesystem and path handling functions, file stat and script introspection.

Some utilities related to “string” and “table” such as split, join, insertSorted, etc.

lun

lun = lubyk networking

Contains the classes used for networking such as:

• Socket
• WebServer
• DavServer
• Service
• ServiceBrowser

lup

lup = lubyk processing

Network transparency and plug & play layer.

• Morph
• Process
• Node
• Inlet
• Outlet
• etc

lug

lug = lubyk graphics and geometry

Contains core classes for vectors, quaternions, small matrices and buffers.

• V2, V3, V4
• M4
• Mem (C array)
• Raster (view on C array = matrix/image/vector)

Dependencies

These modules depend on each other in the following way (the arrow means “depends on” :

  lub <- lut
      <- luf  <- lun  <- lup
      <- lug