doc: add documentation build infrastructure

.gitignore

@@ -12,6 +12,7 @@ test/*
 *.tar
 *.log
 spec/unit/data
+doc/html
 
 emu
 

Makefile

@@ -127,6 +127,7 @@ clean:
 dist-clean: clean
 	rm -rf $(INSTALL_DIR)
 	$(MAKE) -C $(KOR_BASE) dist-clean
+	$(MAKE) -C doc clean
 
 # Don't bundle launchpad on touch devices..
 ifeq ($(TARGET), kindle-legacy)
@@ -324,4 +325,7 @@ static-check:
 		echo "[!] luacheck not found. "\
 		"you can install it with 'luarocks install luacheck'"; fi
 
-.PHONY: test
+doc:
+	make -C doc
+
+.PHONY: test doc

doc/Makefile

@@ -0,0 +1,8 @@
+all:
+ifeq (,$(shell which ldoc))
+	$(error ldoc not found, please install via luarocks.)
+endif
+	ldoc .
+
+clean:
+	rm -rf html

doc/config.ld

@@ -0,0 +1,12 @@
+project = 'KOReader'
+description = 'Multi-platform ebook reader'
+full_description = 'An ebook reader application supports PDF, DJVU, EPUB, FB2 and many more formats, running on Kindle, Kobo, PocketBook, Ubuntu Touch and Android devices.'
+title = 'KOReader Documentation'
+dir = 'html'
+style = '!fixed'
+use_markdown_titles = true
+readme = '../README.md'
+package = ''
+format = 'markdown'
+sort_modules=true
+file = '../frontend'

frontend/MD5.lua

@@ -1,3 +1,6 @@
+--[[--
+MD5 hash library.
+  ]]
 
 local ffi = require "ffi"
 local bit = require "bit"
@@ -210,15 +213,22 @@ end
 
 local md5 = {}
 
+--- Create a new md5 hashing instance.
+---- @return md5 instance
 function md5:new()
     self.ctx = ffi.new("MD5_CTX")
     MD5Init(self.ctx)
 end
 
+--- Feed content to md5 hashing instance.
+---- @param luastr Lua string
 function md5:update(luastr)
     MD5Update(self.ctx, ffi.cast("const char*", luastr), #luastr)
 end
 
+--- Calcualte md5 sum.
+---- @param luastr Lua string
+---- @return md5 sum in Lua string
 function md5:sum(luastr)
     local buf = ffi.new("char[33]")
     local hash = ffi.new("uint8_t[16]")

frontend/apps/reader/pluginloader.lua

@@ -19,16 +19,16 @@ function PluginLoader:loadPlugins()
             local package_cpath = package.cpath
             package.path = path.."/?.lua;"..package.path
             package.cpath = path.."/lib/?.so;"..package.cpath
-            local ok, module = pcall(dofile, mainfile)
+            local ok, plugin_module = pcall(dofile, mainfile)
             if not ok then
-                DEBUG("Error when loading", mainfile, module)
+                DEBUG("Error when loading", mainfile, plugin_module)
             end
             package.path = package_path
             package.cpath = package_cpath
             if ok then
-                module.path = path
+                plugin_module.path = path
-                module.name = module.name or path:match("/(.-)%.koplugin")
+                plugin_module.name = plugin_module.name or path:match("/(.-)%.koplugin")
-                table.insert(self.plugins, module)
+                table.insert(self.plugins, plugin_module)
             end
         end
     end
@@ -44,4 +44,3 @@ function PluginLoader:loadPlugins()
 end
 
 return PluginLoader
-

frontend/apps/reader/readerui.lua

@@ -71,9 +71,9 @@ local ReaderUI = InputContainer:new{
     postInitCallback = nil,
 }
 
-function ReaderUI:registerModule(name, module, always_active)
+function ReaderUI:registerModule(name, ui_module, always_active)
-    if name then self[name] = module end
+    if name then self[name] = ui_module end
-    table.insert(always_active and self.active_widgets or self, module)
+    table.insert(always_active and self.active_widgets or self, ui_module)
 end
 
 function ReaderUI:registerPostInitCallback(callback)
@@ -298,9 +298,9 @@ function ReaderUI:init()
     })
 
     -- koreader plugins
-    for _,module in ipairs(PluginLoader:loadPlugins()) do
+    for _,plugin_module in ipairs(PluginLoader:loadPlugins()) do
-        DEBUG("Loaded plugin", module.name, "at", module.path)
+        DEBUG("Loaded plugin", plugin_module.name, "at", plugin_module.path)
-        self:registerModule(module.name, module:new{
+        self:registerModule(plugin_module.name, plugin_module:new{
             dialog = self.dialog,
             view = self.view,
             ui = self,

frontend/optmath.lua

@@ -1,5 +1,5 @@
---[[
+--[[--
-Simple math helper function
+Simple math helper functions
 ]]--
 
 local Math = {}

frontend/util.lua

@@ -1,3 +1,7 @@
+--[[--
+Miscellaneous helper functions for KOReader frontend.
+  ]]
+
 local util = {}
 
 function util.stripePunctuations(word)
@@ -66,7 +70,9 @@ function util.secondsToClock(seconds, withoutSeconds)
     end
 end
 
--- returns number of keys in a table
+--- Returns number of keys in a table.
+---- @param T Lua table
+---- @return number of keys in table T
 function util.tableSize(T)
     local count = 0
     for _ in pairs(T) do count = count + 1 end