added type annotations and descriptions for functions where appropriate

build.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 LUA=${LUA:-lua}
 rm -r target/*
-mkdir target &>/dev/null
+mkdir -p target/doc &>/dev/null
 $LUA luapreproc.lua module/init.lua target/init.lua
 echo _OSVERSION=\"PsychOS 2.0a2-$(git rev-parse --short HEAD)\" > target/version.lua
 cat target/version.lua target/init.lua > target/tinit.lua
@@ -10,4 +10,5 @@ cp -r service/ lib/ cfg/ target/
 rm target/version.lua
 rm -r doc/
 $LUA finddesc.lua doc/ $(find lib/ module/ -type f|sort)
-pandoc doc/apidoc.md --template=template.tex -o doc/apidoc.pdf
+$LUA gendoc.lua target/doc/kernel.dict $(find module/ -type f|sort)
+pandoc doc/apidoc.md docs-metadata.yml --template=template.tex -o doc/apidoc.pdf

docs-metadata.yml

@@ -0,0 +1,3 @@
+---
+title: 'PsychOS API Documentation'
+---

gendoc.lua

@@ -0,0 +1,51 @@
+#!/usr/bin/env lua
+local doc = require "lib/doc"
+local ser = require "lib/serialization"
+local tA = {...}
+
+local outpath = table.remove(tA,1)
+
+print(outpath)
+
+local function formatDocs(fd)
+ local rs = ""
+ for name,finfo in pairs(fd) do
+  if rs:len() > 0 then
+   rs = rs .. "\n\n"
+  end
+  local as = ""
+  for k,v in pairs(finfo.args) do
+   if k > 1 then
+    as = as .. ", "
+   end
+   as = as .. v[1]
+   if v[2] then
+    as = as .. "^"..v[2].."^"
+   end
+  end
+  local rt = ""
+  for k,v in pairs(finfo.outtypes or {}) do
+   if rt:len() > 0 then
+    rt = rt .. ", "
+   else
+    rt = ": "
+   end
+   rt = rt .. v
+  end
+  rs = string.format("%s## %s(%s)%s\n%s",rs,name,as,rt,finfo.description)
+ end
+ return rs
+end
+
+local ad = io.open(outpath,"wb")
+
+for k,v in pairs(tA) do
+ local fd = doc.parsefile(v)
+ local ds = ser.serialize(fd)
+ local tn = v:match("/(.+)$")
+ if ds:len() > 3 then
+  ad:write(tn.."\t"..ds:gsub("\n",""):gsub(",  +",",").."\n")
+ end
+end
+
+ad:close()

lib/doc.lua

@@ -1,3 +1,4 @@
+local _,serial = pcall(require,"serialization")
 local doc = {}
 doc.searchers = {}
 doc.tctab = {
@@ -96,6 +97,20 @@ function doc.searchers.lib(name) -- string -- string string -- Tries to find a d
  if not dt then return false, "unable to find documentation for "..tostring(name) end
  return doc.format(dt)
 end
+function doc.searchers.cdoc(topic) -- string -- string string -- Searches for documentation labelled as *topic* in .dict files under /boot/doc/
+ if not serial then return end
+ for k,v in ipairs(fs.list("/boot/doc")) do
+  if v:sub(-5) == ".dict" then
+   local f=io.open("/boot/doc/"..v,"rb")
+   for line in f:lines() do
+    local mname, docs = line:match("^(.-)\t(.+)$")
+    if mname == topic or mname == topic..".lua" then
+     return doc.format(serial.unserialize(docs))
+    end
+   end
+  end
+ end
+end
 
 function doc.docs(topic) -- string -- boolean -- Displays the documentation for *topic*, returning true, or errors. Also callable as just doc().
  local lib = os.getenv("LIB") or "/boot/lib"

lib/shutil.lua

@@ -19,7 +19,7 @@ local function wrapUnits(n)
  return tostring(math.floor(n))..(scale[count] or "")
 end
 
-function shutil.import(lib)
+function shutil.import(lib) -- string -- boolean -- Imports the functions from library *lib* into the shell environment.
  local cE = os.getenv("INCLUDE") or shell.include
  local nE = {}
  for k,v in pairs(cE) do
@@ -31,7 +31,7 @@ function shutil.import(lib)
  return true
 end
 
-function shutil.unimport(lib)
+function shutil.unimport(lib) -- string -- boolean -- Removes the functions from *lib* from the shell environment.
  local cE = os.getenv("INCLUDE") or shell.include
  local nE = {}
  for k,v in pairs(cE) do
@@ -43,7 +43,7 @@ function shutil.unimport(lib)
  return true
 end
 
-function shutil.ls(...)
+function shutil.ls(...) -- string -- -- Prints contents of directories specified as *...*.
  local tA = {...}
  if not tA[1] then tA[1] = "." end
  for _,d in ipairs(tA) do
@@ -56,7 +56,7 @@ function shutil.ls(...)
  end
 end
 
-function shutil.cat(...)
+function shutil.cat(...) -- string -- -- Outputs the contents of files specified in *...* to the standard output.
  for _,fn in ipairs({...}) do
   local f = io.open(fn,"rb")
   io.write(f:read("*a"))
@@ -64,7 +64,7 @@ function shutil.cat(...)
  end
 end
 
-function shutil.ps()
+function shutil.ps() -- Prints the processes running on the system.
  print("PID# Parent | Name")
  for k,v in pairs(os.tasks()) do
   local t = os.taskInfo(v)
@@ -72,7 +72,7 @@ function shutil.ps()
  end
 end
 
-function shutil.df()
+function shutil.df() -- Prints free disk space.
  local mt = fs.mounts()
  local ml = 0
  for k,v in pairs(mt) do
@@ -88,7 +88,7 @@ function shutil.df()
  end
 end
 
-function shutil.mount(addr,path)
+function shutil.mount(addr,path) -- string string -- boolean string -- Mounts filesystem component with address *addr* to *path* in the filesystem.
  if not addr then
   local mt = fs.mounts()
   for k,v in pairs(mt) do
@@ -114,7 +114,7 @@ function shutil.mount(addr,path)
  end
 end
 
-function shutil.free()
+function shutil.free() -- Displays used and free memory.
  print("Total  Used  Free")
  print(string.format("%5s %5s %5s",wrapUnits(computer.totalMemory()),wrapUnits(computer.totalMemory()-computer.freeMemory()),wrapUnits(computer.freeMemory())))
 end

lib/unionfs.lua

@@ -4,7 +4,7 @@ local function normalise(path)
  return table.concat(fs.segments(path),"/")
 end
 
-function unionfs.create(...)
+function unionfs.create(...) -- string -- table -- Returns a unionfs object of the directories specified in *...*.
  local paths,fids,fc = {...}, {}, 0
  for k,v in pairs(paths) do
   paths[k] = "/"..normalise(v)

lib/vtansi.lua

@@ -1,5 +1,5 @@
 local vtansi = {}
-function vtansi.vtemu(gpu) -- takes GPU component proxy *gpu* and returns a function to write to it in a manner like an ANSI terminal
+function vtansi.vtemu(gpu) -- table -- function -- takes GPU component proxy *gpu* and returns a function to write to it in a manner like an ANSI terminal
  local colours = {0x0,0xFF0000,0x00FF00,0xFFFF00,0x0000FF,0xFF00FF,0x00B6FF,0xFFFFFF}
  local mx, my = gpu.maxResolution()
  local cx, cy = 1, 1
@@ -142,7 +142,7 @@ function vtansi.vtemu(gpu) -- takes GPU component proxy *gpu* and returns a func
  return termwrite
 end
 
-function vtansi.vtsession(gpua,scra) -- creates a process to handle the GPU and screen address combination *gpua*/*scra*. Returns read, write and "close" functions.
+function vtansi.vtsession(gpua,scra) -- string string -- table -- creates a process to handle the GPU and screen address combination *gpua*/*scra*. Returns read, write and "close" functions.
  local gpu = component.proxy(gpua)
  gpu.bind(scra)
  local write = vtansi.vtemu(gpu)

luapreproc.lua

@@ -181,6 +181,7 @@ env:process(arg[1])
 local tmpfile = os.tmpname()
 if tmpfile:sub(#tmpfile) == "." then tmpfile = tmpfile:sub(1, #tmpfile - 1) end
 local tmpf = io.open(tmpfile, "wb")
+env.code = env.code:gsub("%-%-.-\n","\n"):gsub("\n\n","\n")
 tmpf:write(env.code)
 tmpf:close()
 --if (os.execute("lua minify.lua "..tmpfile.." > "..arg[2])) then

module/buffer.lua

@@ -2,7 +2,7 @@
 
 buffer = {}
 
-function buffer.new(mode, stream) -- create a new buffer in mode *mode* backed by stream object *stream*
+function buffer.new(mode, stream) -- string table -- table -- create a new buffer in mode *mode* backed by stream object *stream*
  local result = {
   mode = {},
   stream = stream,

module/devfs.lua

@@ -64,7 +64,7 @@ end
 devfs.component.address = "devfs"
 devfs.component.type = "devfs"
 
-function devfs.register(fname,fopen) -- Register a new devfs node with the name *fname* that will run the function *fopen* when opened. This function should return a function for read, a function for write, function for close, and optionally, a function for seek, in that order.
+function devfs.register(fname,fopen) -- string function -- -- Register a new devfs node with the name *fname* that will run the function *fopen* when opened. This function should return a function for read, a function for write, function for close, and optionally, a function for seek, in that order.
  devfs.files[fname] = fopen
 end
 

module/fs.lua

@@ -3,14 +3,14 @@ fs = {}
 local fsmounts = {}
 
 -- basics
-function fs.segments(path) -- splits *path* on each /
+function fs.segments(path) -- string -- table -- Splits *path* on each /
  local segments = {}
  for segment in path:gmatch("[^/]+") do
   segments[#segments+1] = segment
  end
  return segments
 end
-function fs.resolve(path) -- resolves *path* to a specific filesystem mount and path
+function fs.resolve(path) -- string -- string string -- Resolves *path* to a specific filesystem mount and path
  if not path or path == "." then path = os.getenv("PWD") end
  if path:sub(1,1) ~= "/" then path=(os.getenv("PWD") or "").."/"..path end
  local segments, rpath, rfs= fs.segments(path)
@@ -44,7 +44,7 @@ local function fclose(self)
  return fsmounts[self.fs].close(self.fid)
 end
 
-function fs.open(path,mode) -- opens file *path* with mode *mode*
+function fs.open(path,mode) -- string string -- table -- Opens file *path* with mode *mode*, returning a file object.
  mode = mode or "rb"
  local fsi,path = fs.resolve(path)
  if not fsmounts[fsi] then return false end
@@ -62,7 +62,7 @@ function fs.open(path,mode) -- opens file *path* with mode *mode*
  return false
 end
 
-function fs.copy(from,to) -- copies a file from *from* to *to*
+function fs.copy(from,to) -- string string -- boolean -- copies a file from *from* to *to*
  local of = fs.open(from,"rb")
  local df = fs.open(to,"wb")
  if not of or not df then
@@ -71,33 +71,34 @@ function fs.copy(from,to) -- copies a file from *from* to *to*
  df:write(of:read("*a"))
  df:close()
  of:close()
+ return true
 end
 
-function fs.rename(from,to) -- moves file *from* to *to*
+function fs.rename(from,to) -- string string -- boolean -- Moves file *from* to *to*
  local ofsi, opath = fs.resolve(from)
  local dfsi, dpath = fs.resolve(to)
  if ofsi == dfsi then
   fsmounts[ofsi].rename(opath,dpath)
   return true
  end
- fs.copy(from,to)
+ if not fs.copy(from,to) then return false end
- fs.remove(from)
+ if not fs.remove(from) then return false end
  return true
 end
 
-function fs.mount(path,proxy) -- mounts the filesystem *proxy* to the mount point *path* if it is a directory. BYO proxy.
+function fs.mount(path,proxy) -- string table -- boolean -- Mounts the filesystem *proxy* to the mount point *path* if it is a directory. BYO proxy.
  if fs.isDirectory(path) and not fsmounts[table.concat(fs.segments(path),"/")] then
   fsmounts[table.concat(fs.segments(path),"/")] = proxy
   return true
  end
  return false, "path is not a directory"
 end
-function fs.umount(path)
+function fs.umount(path) -- string -- -- Unmounts filesystem from *path*.
  local fsi,_ = fs.resolve(path)
  fsmounts[fsi] = nil
 end
 
-function fs.mounts() -- returns a table containing the mount points of all mounted filesystems
+function fs.mounts() -- -- table -- Returns a table containing the mount points of all mounted filesystems
  local rt = {}
  for k,v in pairs(fsmounts) do
   rt[#rt+1] = k,v.address or "unknown"
@@ -105,11 +106,11 @@ function fs.mounts() -- returns a table containing the mount points of all mount
  return rt
 end
 
-function fs.address(path) -- returns the address of the filesystem at a given path, if applicable; do not expect a sensical response
+function fs.address(path) -- string -- string -- Returns the address of the filesystem at a given path, if applicable; do not expect a sensical response
  local fsi,_ = fs.resolve(path)
  return fsmounts[fsi].address
 end
-function fs.type(path) -- returns the component type of the filesystem at a given path, if applicable
+function fs.type(path) -- string -- string -- Returns the component type of the filesystem at a given path, if applicable
  local fsi,_ = fs.resolve(path)
  return fsmounts[fsi].type or "filesystem"
 end

module/io.lua

@@ -1,12 +1,12 @@
 io = {}
 
-function io.open(path,mode) -- Open file *path* in *mode*. Returns a buffer object.
+function io.open(path,mode) -- string string -- table -- Open file *path* in *mode*. Returns a buffer object.
  local f,e = fs.open(path, mode)
  if not f then return false, e end
  return buffer.new(mode,f)
 end
 
-function io.input(fd) -- Sets the default input stream to *fd* if provided, either as a buffer as a path. Returns the default input stream.
+function io.input(fd) -- table -- table -- Sets the default input stream to *fd* if provided, either as a buffer as a path. Returns the default input stream.
  if type(fd) == "string" then
   fd=io.open(fd,"rb")
  end
@@ -15,7 +15,7 @@ function io.input(fd) -- Sets the default input stream to *fd* if provided, eith
  end
  return os.getenv("STDIN")
 end
-function io.output(fd) -- Sets the default output stream to *fd* if provided, either as a buffer as a path. Returns the default output stream.
+function io.output(fd) -- table -- table -- Sets the default output stream to *fd* if provided, either as a buffer as a path. Returns the default output stream.
  if type(fd) == "string" then
   fd=io.open(fd,"wb")
  end

module/loadfile.lua

@@ -1,19 +1,19 @@
-function loadfile(p) -- reads file *p* and returns a function if possible
+function loadfile(p) -- string -- function -- reads file *p* and returns a function if possible
  local f = io.open(p,"rb")
  local c = f:read("*a")
  f:close()
  return load(c,p,"t")
 end
-function runfile(p,...) -- runs file *p* with arbitrary arguments in the current thread
+function runfile(p,...) -- string -- -- runs file *p* with arbitrary arguments in the current thread
  return loadfile(p)(...)
 end
-function os.spawnfile(p,n,...) -- spawns a new process from file *p* with name *n*, with arguments following *n*.
+function os.spawnfile(p,n,...) -- string string -- number -- spawns a new process from file *p* with name *n*, with arguments following *n*.
  local tA = {...}
  return os.spawn(function() local res={pcall(loadfile(p), table.unpack(tA))} computer.pushSignal("process_finished", os.pid(), table.unpack(res)) dprint(table.concat(res)) end,n or p)
 end
 _G.package = {}
 package.loaded = {computer=computer,component=component,fs=fs,buffer=buffer}
-function require(f,force) -- searches for a library with name *f* and returns what the library returns, if possible. if *force* is set, loads the library even if it is cached
+function require(f,force) -- string boolean -- table -- searches for a library with name *f* and returns what the library returns, if possible. if *force* is set, loads the library even if it is cached
  if not package.loaded[f] or force then
   local lib = os.getenv("LIB") or "/boot/lib"
   for d in lib:gmatch("[^\n]+") do
@@ -29,6 +29,6 @@ function require(f,force) -- searches for a library with name *f* and returns wh
  end
  error("library not found: "..f)
 end
-function reload(f)
+function reload(f) -- string -- table -- Reloads library *f* from disk into memory.
  return require(f,true)
 end

module/osutil.lua

@@ -1,4 +1,4 @@
-function os.chdir(p) -- changes the current working directory of the calling process to the directory specified in *p*, returning true or false, error
+function os.chdir(p) -- string -- boolean string -- changes the current working directory of the calling process to the directory specified in *p*, returning true or false, error
  if not (p:sub(1,1) == "/") then
   local np = {}
   for k,v in pairs(fs.segments(os.getenv("PWD").."/"..p)) do

module/sched.lua

@@ -1,6 +1,6 @@
 do
 local tTasks,nPid,nTimeout,cPid = {},1,0.25,0 -- table of tasks, next process ID, event timeout, current PID
-function os.spawn(f,n) -- creates a process from function *f* with name *n*
+function os.spawn(f,n) -- function string -- number -- creates a process from function *f* with name *n*
  tTasks[nPid] = {
   c=coroutine.create(f), -- actual coroutine
   n=n, -- process name
@@ -16,20 +16,20 @@ function os.spawn(f,n) -- creates a process from function *f* with name *n*
  nPid = nPid + 1
  return nPid - 1
 end
-function os.kill(pid) -- removes process *pid* from the task list
+function os.kill(pid) -- number -- -- removes process *pid* from the task list
  tTasks[pid] = nil
 end
-function os.pid() -- returns the current process' PID
+function os.pid() -- -- number -- returns the current process' PID
  return cPid
 end
-function os.tasks() -- returns a table of process IDs
+function os.tasks() -- -- table -- returns a table of process IDs
  local rt = {}
  for k,v in pairs(tTasks) do
   rt[#rt+1] = k
  end
  return rt
 end
-function os.taskInfo(pid) -- returns info on process *pid* as a table with name and parent values
+function os.taskInfo(pid) -- number -- table -- returns info on process *pid* as a table with name and parent values
  pid = pid or os.pid()
  if not tTasks[pid] then return false end
  return {name=tTasks[pid].n,parent=tTasks[pid].P}

module/syslog.lua

@@ -9,6 +9,7 @@ syslog.notice = 5
 syslog.info = 6
 syslog.debug = 7
 
+-- function syslog(msg, level, service) -- string number string -- -- Output *msg* to the system log, with severity *level*, from *service*.
 local rdprint=dprint or function() end
 setmetatable(syslog,{__call = function(_,msg, level, service)
  level, service = level or syslog.info, service or (os.taskInfo(os.pid()) or {}).name or "unknown"