added type annotations to documentation for various libraries

Doesn't seem to break anything, though I wish Microsoft would fix their filesystems.

Markdown changes are a nice touch, though they'll be replaced soon.

Might think about using #!/usr/bin/env for Lua at some point.

build.sh

@@ -1,10 +1,11 @@
-#!/bin/sh
+#!/bin/bash
+LUA=${LUA:-lua}
 rm -r target/*
 mkdir target &>/dev/null
-lua luapreproc.lua module/init.lua target/init.lua
+$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
 mv target/tinit.lua target/init.lua
 cp -r service/ lib/ cfg/ target/
-lua finddesc.lua $(find module/ -type f) $(find lib/ -type f) > apidoc.md
+$LUA finddesc.lua $(find module/ -type f) $(find lib/ -type f) > apidoc.md
 rm target/version.lua

finddesc.lua

@@ -12,14 +12,14 @@ for _,file in pairs(tA) do
  for k,v in pairs(lines) do
   local name, args, desc = v:match("function%s+(.+)%s*%((.*)%)%s*%-%-%s*(.+)")
   if name and args and desc then
-   docfiles[file][#docfiles[file]+1] = string.format("##%s(%s)\n%s",name,args,desc)
+   docfiles[file][#docfiles[file]+1] = string.format("## %s(%s)\n%s\n",name,args,desc)
   end
  end
 end
 
 for k,v in pairs(docfiles) do
  if #v > 0 then
-  print("#"..k)
+  print("\n# "..k)
   for l,m in pairs(v) do
    print(m)
   end

lib/event.lua

@@ -1,5 +1,5 @@
 local event = {}
-function event.pull(t,...) -- return an event, optionally with timeout *t* and filter *...*.
+function event.pull(t,...) -- number -- -- return an event, optionally with timeout *t* and filter *...*.
  local tA = {...}
  if type(t) == "string" then
   table.insert(tA,1,t)
@@ -26,7 +26,7 @@ function event.pull(t,...) -- return an event, optionally with timeout *t* and f
  return nil
 end
 
-function event.listen(e,f) -- run function *f* for every occurance of event *e*
+function event.listen(e,f) -- string function -- -- run function *f* for every occurance of event *e*
  os.spawn(function() while true do
   local tEv = {coroutine.yield()}
   if tEv[1] == e then
@@ -36,7 +36,7 @@ function event.listen(e,f) -- run function *f* for every occurance of event *e*
  end end,string.format("[%d] %s listener",os.pid(),e))
 end
 
-function event.ignore(e,f) -- stop function *f* running for every occurance of event *e*
+function event.ignore(e,f) -- string function -- stop function *f* running for every occurance of event *e*
  computer.pushSignal("unlisten",e,tostring(f))
 end
 

lib/minitel.lua

@@ -12,7 +12,7 @@ net.minport = 32768
 net.maxport = 65535
 net.openports = {}
 
-function net.genPacketID() -- generate a random 16-character string, for use in packet IDs
+function net.genPacketID() -- -- string -- generate a random 16-character string, for use in packet IDs
  local npID = ""
  for i = 1, 16 do
   npID = npID .. string.char(math.random(32,126))
@@ -20,11 +20,11 @@ function net.genPacketID() -- generate a random 16-character string, for use in
  return npID
 end
 
-function net.usend(to,port,data,npID) -- send an unreliable packet to host *to* on port *port* with data *data*, optionally with the packet ID *npID*
+function net.usend(to,port,data,npID) -- string number string string -- -- send an unreliable packet to host *to* on port *port* with data *data*, optionally with the packet ID *npID*
  computer.pushSignal("net_send",0,to,port,data,npID)
 end
 
-function net.rsend(to,port,data,block) -- send a reliable packet to host *to* on port *port* with data *data*, with *block* set to true to disable blocking
+function net.rsend(to,port,data,block) -- string number string boolean -- boolean -- send a reliable packet to host *to* on port *port* with data *data*, with *block* set to true to disable blocking
  local pid, stime = net.genPacketID(), computer.uptime() + net.streamdelay
  computer.pushSignal("net_send",1,to,port,data,pid)
  if block then return false end
@@ -37,7 +37,7 @@ end
 
 -- ordered packet delivery, layer 4?
 
-function net.send(to,port,ldata) -- send arbitrary data *ldata* reliably to host *to* on port *port*
+function net.send(to,port,ldata) -- string number string -- boolean -- send arbitrary data *ldata* reliably to host *to* on port *port*
  local tdata = {}
  if ldata:len() > net.mtu then
   for i = 1, ldata:len(), net.mtu do
@@ -112,7 +112,7 @@ local function socket(addr,port,sclose)
  return conn
 end
 
-function net.open(to,port) -- open a socket to host *to* on port *port*
+function net.open(to,port) -- string number -- buffer -- open a socket to host *to* on port *port*
  if not net.rsend(to,port,"openstream") then return false, "no ack from host" end
  local st = computer.uptime()+net.streamdelay
  local est = false
@@ -139,7 +139,7 @@ function net.open(to,port) -- open a socket to host *to* on port *port*
  return socket(to,data,sclose)
 end
 
-function net.listen(port) -- listen for connections on port *port* in a blocking manner
+function net.listen(port) -- number -- buffer -- listen for connections on port *port* in a blocking manner
  repeat
   _, from, rport, data = event.pull("net_msg")
  until rport == port and data == "openstream"
@@ -150,7 +150,7 @@ function net.listen(port) -- listen for connections on port *port* in a blocking
  return socket(from,nport,sclose)
 end
 
-function net.flisten(port,listener) -- run function *listener* on a connection to *port*
+function net.flisten(port,listener) -- number function -- function -- run function *listener* on a connection to *port*
  local function helper(_,from,rport,data)
   if rport == port and data == "openstream" then
    local nport = math.random(net.minport,net.maxport)

lib/rc.lua

@@ -22,7 +22,7 @@ local function saveConfig()
  return true
 end
 
-function rc.load(name,force)
+function rc.load(name,force) -- string boolean -- table -- Attempts to load service *name*, and if *force* is true, replaces the current instance.
  if force then
   rc.stop(name)
   service[name] = nil
@@ -35,7 +35,7 @@ function rc.load(name,force)
  return res
 end
 
-function rc.stop(name,...)
+function rc.stop(name,...) -- string -- boolean string -- Stops service *name*, supplying *...* to the stop function. Returns false and a reason if this fails.
  if not service[name] then return false, "service not found" end
  if service[name].stop then
   service[name].stop(...)
@@ -47,7 +47,7 @@ function rc.stop(name,...)
  rc.pids[name] = nil
 end
 
-function rc.start(name,...)
+function rc.start(name,...) -- string -- boolean string -- Stops service *name*, supplying *...* to the stop function. Returns false and a reason if this fails.
  rc.load(name)
  if not service[name] then return false, "service not found" end
  local rv = {service[name].start(...)}
@@ -56,19 +56,19 @@ function rc.start(name,...)
  end
 end
 
-function rc.restart(name)
+function rc.restart(name) -- string -- -- Restarts service *name* using rc.stop and rc.start.
  rc.stop(name)
  rc.start(name)
 end
 
-function rc.enable(name)
+function rc.enable(name) -- string -- -- Enables service *name* being started on startup.
  for k,v in pairs(cfg.enabled) do
   if v == name then return false end
  end
  cfg.enabled[#cfg.enabled+1] = name
  saveConfig()
 end
-function rc.disable(name)
+function rc.disable(name) -- string -- -- Disables service *name* being started on startup.
  local disabled = false
  for k,v in pairs(cfg.enabled) do
   if v == name then table.remove(cfg.enabled,k) disabled = true break end

lib/rpc.lua

@@ -27,7 +27,7 @@ function rpcf.list()
  return rt
 end
 
-function rpc.call(hostname,fn,...)
+function rpc.call(hostname,fn,...) -- string string -- boolean -- Calls exported function *fn* on host *hostname*, with parameters *...*, returning whatever the function returns, or false.
  if hostname == "localhost" then
   return rpcf[fn](...)
  end
@@ -44,7 +44,7 @@ function rpc.call(hostname,fn,...)
  end
  return false
 end
-function rpc.proxy(hostname,filter)
+function rpc.proxy(hostname,filter) -- string string -- table -- Returns a component.proxy()-like table from the functions on *hostname* with names matching *filter*.
  filter=(filter or "").."(.+)"
  local fnames = rpc.call(hostname,"list")
  if not fnames then return false end
@@ -59,7 +59,7 @@ function rpc.proxy(hostname,filter)
  end
  return rt
 end
-function rpc.register(name,fn)
+function rpc.register(name,fn) -- string function -- -- Registers a function to be exported by the RPC library.
  local rpcrunning = false
  for k,v in pairs(os.tasks()) do
   if os.taskInfo(v).name == "rpc daemon" then

lib/serialization.lua

@@ -3,7 +3,7 @@ local local_pairs=function(tbl)
  local mt=getmetatable(tbl)
  return (mt and mt.__pairs or pairs)(tbl)
 end
-function serial.serialize(value,af) -- serialize *value* into a string. If *af* is true, allow functions. This breaks unserialization.
+function serial.serialize(value,af) -- boolean -- string -- serialize *value* into a string. If *af* is true, allow functions. This breaks unserialization.
  local kw={["and"]=true,["break"]=true,["do"]=true,["else"]=true,["elseif"]=true,["end"]=true,["false"]=true,["for"]=true,["function"]=true,["goto"]=true,["if"]=true,["in"]=true,["local"]=true,["nil"]=true,["not"]=true,["or"]=true,["repeat"]=true,["return"]=true,["then"]=true,["true"]=true,["until"]=true,["while"]=true}
  local id="^[%a_][%w_]*$"
  local ts={}
@@ -40,7 +40,7 @@ function serial.serialize(value,af) -- serialize *value* into a string. If *af*
   else error("ut "..t) end end
  return s(value, 1)
 end
-function serial.unserialize(data) -- return *data*, but unserialized
+function serial.unserialize(data) -- string -- -- return *data*, but unserialized
  checkArg(1, data, "string")
  local result, reason = load("return " .. data, "=data", _, {math={huge=math.huge}})
  if not result then return nil, reason end

luapreproc.lua

@@ -179,6 +179,7 @@ local env = {code = ""}
 setmetatable(env, {__index=_env})
 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")
 tmpf:write(env.code)
 tmpf:close()