added type annotations and function documentation to liblz16 and pkgfs

README.md

@@ -6,16 +6,25 @@ A lightweight, multi-user operating system for OpenComputers
 
 ### The kernel
 
-The kernel can be built using luapreproc:
+The kernel is composed of a number of modules, found in the *module/* directory. Which modules are included can be customised by changing the include statements in *module/init.lua*; copying it and customizing that is recommended, so you can *git pull* later without having to stash or reset your changes.
 
-    ./luapreproc.lua module/init.lua kernel.lua
+#### Unix-like systems
+
+The kernel can be built using the preproc library and provided scripts:
+
+    lua build.lua module/init.lua kernel.lua
+
+#### PsychOS
+
+The kernel can be built from inside PsychOS using the preproc library, assuming you have the kernel source available:
+
+    preproc("module/init.lua","kernel.lua")
 
 ### The boot filesystem
 
 A boot filesystem contains several things:
 
  - The kernel, as init.lua
- - The exec/ directory, as this contains all executables
  - The lib/ directory, containing libraries
  - The service/ directory, containing system services
 
@@ -23,6 +32,4 @@ This has been automated in the form of build.sh, pending a real makefile.
 
 ## Documentation
 
-To generate function documentation, run:
-
-    ./finddesc.lua module/* lib/* > apidoc.md
+Documentation is generated as the system is built with build.sh; a set of markdown files will be placed into *doc/*, as well as an all-in-one *apidoc.md*. If pandoc is installed, an *apidoc.pdf* will also be generated.

lib/liblz16.lua

@@ -54,14 +54,14 @@ local function writeBuffer(fo)
  return buffer.new("wb",stream)
 end
 
-function lz16.buffer(stream)
+function lz16.buffer(stream) -- table -- table -- Wrap a stream to read or write LZ16.
  if stream.mode.w then
   return writeBuffer(stream)
  end
  return readBuffer(stream)
 end
 
-function lz16.open(fname, mode)
+function lz16.open(fname, mode) -- string string -- table -- Open file *fname* to read or write LZ16-compressed data depending on *mode*
  local f = io.open(fname, mode)
  if not f then return false end
  f.mode.b = true

lib/pkgfs.lua

@@ -98,7 +98,7 @@ function pkgfs.component.close(handle)
  return true
 end
 
-function pkgfs.add(fname,comp)
+function pkgfs.add(fname,comp) -- string boolean -- -- Add a package as specified in *fname* to the pkgfs component. If *comp* is true, read it as a LZ16-compressed package.
  if fname:sub(1,1) ~= "/" then
   fname = "/"..fnormalize(os.getenv("PWD").."/"..fname)
  end