From e2096ed8d9bf448d73f216d8a0b35f15c0929ad0 Mon Sep 17 00:00:00 2001 From: Qingping Hou Date: Thu, 4 Feb 2016 10:24:39 -0800 Subject: [PATCH] doc: add documentation build infrastructure --- .gitignore | 1 + Makefile | 6 +++++- doc/Makefile | 8 ++++++++ doc/config.ld | 12 ++++++++++++ frontend/MD5.lua | 10 ++++++++++ frontend/apps/reader/pluginloader.lua | 11 +++++------ frontend/apps/reader/readerui.lua | 12 ++++++------ frontend/optmath.lua | 4 ++-- frontend/util.lua | 8 +++++++- 9 files changed, 56 insertions(+), 16 deletions(-) create mode 100644 doc/Makefile create mode 100644 doc/config.ld diff --git a/.gitignore b/.gitignore index 8ed738d16..a7b14504f 100644 --- a/.gitignore +++ b/.gitignore @@ -12,6 +12,7 @@ test/* *.tar *.log spec/unit/data +doc/html emu diff --git a/Makefile b/Makefile index e568d96c9..c1cbf572e 100644 --- a/Makefile +++ b/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 diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 000000000..4ef03147a --- /dev/null +++ b/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 diff --git a/doc/config.ld b/doc/config.ld new file mode 100644 index 000000000..9f6ef8cf0 --- /dev/null +++ b/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' diff --git a/frontend/MD5.lua b/frontend/MD5.lua index c8d73ea1f..0e0bbed46 100644 --- a/frontend/MD5.lua +++ b/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]") diff --git a/frontend/apps/reader/pluginloader.lua b/frontend/apps/reader/pluginloader.lua index b94fd03c7..17f76e305 100644 --- a/frontend/apps/reader/pluginloader.lua +++ b/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 - module.name = module.name or path:match("/(.-)%.koplugin") - table.insert(self.plugins, module) + plugin_module.path = path + plugin_module.name = plugin_module.name or path:match("/(.-)%.koplugin") + table.insert(self.plugins, plugin_module) end end end @@ -44,4 +44,3 @@ function PluginLoader:loadPlugins() end return PluginLoader - diff --git a/frontend/apps/reader/readerui.lua b/frontend/apps/reader/readerui.lua index 30d4dd9e1..2ace6e595 100644 --- a/frontend/apps/reader/readerui.lua +++ b/frontend/apps/reader/readerui.lua @@ -71,9 +71,9 @@ local ReaderUI = InputContainer:new{ postInitCallback = nil, } -function ReaderUI:registerModule(name, module, always_active) - if name then self[name] = module end - table.insert(always_active and self.active_widgets or self, module) +function ReaderUI:registerModule(name, ui_module, always_active) + if name then self[name] = ui_module end + 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 - DEBUG("Loaded plugin", module.name, "at", module.path) - self:registerModule(module.name, module:new{ + for _,plugin_module in ipairs(PluginLoader:loadPlugins()) do + DEBUG("Loaded plugin", plugin_module.name, "at", plugin_module.path) + self:registerModule(plugin_module.name, plugin_module:new{ dialog = self.dialog, view = self.view, ui = self, diff --git a/frontend/optmath.lua b/frontend/optmath.lua index 2742b1bfe..38d64b5f0 100644 --- a/frontend/optmath.lua +++ b/frontend/optmath.lua @@ -1,5 +1,5 @@ ---[[ -Simple math helper function +--[[-- +Simple math helper functions ]]-- local Math = {} diff --git a/frontend/util.lua b/frontend/util.lua index 61b017933..6ab3244d1 100644 --- a/frontend/util.lua +++ b/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