diff --git a/doc/Collaborating with Git.md b/doc/Collaborating with Git.md
index 6375b346a..d1d911c74 100644
--- a/doc/Collaborating with Git.md
+++ b/doc/Collaborating with Git.md
@@ -2,10 +2,11 @@
## Basic
If you are new to Git, following are some of the resources you might find useful:
-* [GitHub's blog post][https://github.com/blog/120-new-to-git]
-* http://try.github.com/
-* http://sixrevisions.com/resources/git-tutorials-beginners/
-* http://rogerdudler.github.io/git-guide/
+
+* [GitHub's blog post](https://github.com/blog/120-new-to-git)
+*
+*
+*
## Get latest code from the KOReader repository
First you need to add the official repo to your remote repo list:
diff --git a/doc/Events.md b/doc/Events.md
index c9be03762..7f0c284b9 100644
--- a/doc/Events.md
+++ b/doc/Events.md
@@ -57,6 +57,7 @@ When you call `UIManager:show` on an widget, this widget will be added to the to
Events are sent to the first widget in `UIManager._window_stack`. If it is not consumed, then UIManager will try to send it to all active widgets (`widget.is_always_active` equals `true`) in the `_window_stack`.
## Draw Page Code Path
+
* **in readerview.lua:** ReaderView widget flag itself dirty in `ReaderView:recalculate`
* **in ui.lua:** UI main loop calls `ReaderView:paintTo`
* **in readerview.lua:** `ReaderView:paintTo` calls `document:drawPage`
diff --git a/doc/Hacking.md b/doc/Hacking.md
index aade660df..2dc060d66 100644
--- a/doc/Hacking.md
+++ b/doc/Hacking.md
@@ -19,7 +19,7 @@ Anything printed by `logger.dbg` starts with `DEBUG`.
## Bug hunting in kpv
-A real example for hunting bug in KPV's cache system: https://github.com/koreader/kindlepdfviewer/pull/475
+A real example of bug hunting in KPV's cache system:
## Developing UI widgets ##
diff --git a/doc/Porting.md b/doc/Porting.md
index 4473a8bba..a5e2882a1 100644
--- a/doc/Porting.md
+++ b/doc/Porting.md
@@ -13,6 +13,7 @@ KOReader uses framebuffer to control EInk devices, so the output module here is
[base/ffi/framebuffer_einkfb.lua](https://github.com/koreader/koreader-base/blob/master/ffi/framebuffer_einkfb.lua).
Following are the framebuffers that `framebuffer_einkfb.lua` currently supports:
+
* 4BPP inverted framebuffer
* 16 scale 8BPP inverted framebuffer
* 16 scale 8BPP framebuffer
@@ -32,12 +33,11 @@ flipped in the same way as 4BPP inverted framebuffer does.
If your device's framebuffer does not fit into any of the categories above,
then you need to add a new transformation function in `framebuffer_einkfb.lua`.
-The `framebuffer_einkfb.lua` module works in following ways for non 4BPP framebuffers;
+The `framebuffer_einkfb.lua` module works in following ways for non 4BPP framebuffers:
+
* a shadow buffer is created and structured as 4BPP inverted framebuffer.
* all updates on screen bitmap are temporally written into the shadow buffer.
- * each time we want to reflect the updated bitmap on screen, we translate
- the shadow buffer into a format that the real framebuffer understands and
- write into the mapped memory region. (varies on devices)
+ * each time we want to reflect the updated bitmap on screen, we translate the shadow buffer into a format that the real framebuffer understands and write into the mapped memory region. (varies on devices)
* call ioctl system call to refresh EInk screen. (varies on devices)
KOReader will handle the 4BPP shadow buffer for you, all you need to do is to
@@ -62,19 +62,16 @@ format that KOReader understands. You can look at the KindleTouch initialization
For Kobo devices (Mini, Touch, Glo and Aura HD) the function `Input:eventAdjustHook()` was skipped and the functions `Input:init()` and `Input:handleTypeBTouchEv` were changed to allow the single touch protocol. For Kobo Aura with multitouch support an extra function `Input:handlePhoenixTouchEv` was added.
Linux supports two kinds of Multi-touch protocols:
- * http://www.kernel.org/doc/Documentation/input/multi-touch-protocol.txt
+
+ *
Currently, KOReader supports gesture detection of protocol B, so if your device sends out
protocol A, you need to make a variant of function `Input:handleTouchEv()` (like `Input:handleTypeBTouchEv` and `Input:handlePhoenixTouchEv`) and simulate protocol B.
Also you are welcome to send a PR that adds protocol A support to KOReader.
More information on Linux's input system:
- * http://www.kernel.org/doc/Documentation/input/event-codes.txt
- * http://www.kernel.org/doc/Documentation/input/input.txt
+ *
+ *
-
-[einkfb-c]:https://github.com/koreader/koreader-base/blob/master/einkfb.c
[kb-framework]:https://github.com/koreader/koreader-base
-[inputev]:https://github.com/koreader/koreader/blob/master/frontend/ui/inputevent.lua
-
diff --git a/frontend/device/gesturedetector.lua b/frontend/device/gesturedetector.lua
index 25fdec3f2..8529b1e3b 100644
--- a/frontend/device/gesturedetector.lua
+++ b/frontend/device/gesturedetector.lua
@@ -1,46 +1,51 @@
-local Geom = require("ui/geometry")
-local TimeVal = require("ui/timeval")
-local logger = require("logger")
+--[[--
+This module detects gestures.
---[[
Current detectable gestures:
- * touch (user touched screen)
- * tap (touch action detected as single tap)
- * pan
- * hold
- * swipe
- * pinch
- * spread
- * rotate
- * hold_pan
- * double_tap
- * inward_pan
- * outward_pan
- * pan_release
- * hold_release
- * two_finger_tap
- * two_finger_pan
- * two_finger_swipe
- * two_finger_pan_release
+
+* `touch` (user touched screen)
+* `tap` (touch action detected as single tap)
+* `pan`
+* `hold`
+* `swipe`
+* `pinch`
+* `spread`
+* `rotate`
+* `hold_pan`
+* `double_tap`
+* `inward_pan`
+* `outward_pan`
+* `pan_release`
+* `hold_release`
+* `two_finger_tap`
+* `two_finger_pan`
+* `two_finger_swipe`
+* `two_finger_pan_release`
You change the state machine by feeding it touch events, i.e. calling
-GestureDetector:feedEvent(tev).
+@{GestureDetector:feedEvent|GestureDetector:feedEvent(tev)}.
+
a touch event should have following format:
-tev = {
- slot = 1,
- id = 46,
- x = 0,
- y = 1,
- timev = TimeVal:new{...},
-}
-Don't confuse tev with raw evs from kernel, tev is build according to ev.
+ tev = {
+ slot = 1,
+ id = 46,
+ x = 0,
+ y = 1,
+ timev = TimeVal:new{...},
+ }
+
+Don't confuse `tev` with raw evs from kernel, `tev` is build according to ev.
-GestureDetector:feedEvent(tev) will return a detection result when you
-feed a touch release event to it.
+@{GestureDetector:feedEvent|GestureDetector:feedEvent(tev)} will return a
+detection result when you feed a touch release event to it.
--]]
+local Geom = require("ui/geometry")
+local TimeVal = require("ui/timeval")
+local logger = require("logger")
+
local GestureDetector = {
-- must be initialized with the Input singleton class
input = nil,
@@ -88,6 +93,9 @@ function GestureDetector:init()
self.PAN_THRESHOLD = 50 * self.screen:getDPI() / 167
end
+--[[--
+Feeds touch events to state machine.
+--]]
function GestureDetector:feedEvent(tevs)
repeat
local tev = table.remove(tevs)
@@ -151,9 +159,10 @@ function GestureDetector:isTwoFingerTap()
)
end
---[[
-compare last_pan with first_tev in this slot
-return pan direction and distance
+--[[--
+Compares `last_pan` with `first_tev` in this slot.
+
+@return (direction, distance) pan direction and distance
--]]
function GestureDetector:getPath(slot)
local x_diff = self.last_tevs[slot].x - self.first_tevs[slot].x
@@ -236,8 +245,8 @@ function GestureDetector:initialState(tev)
end
end
---[[
-this method handles both single and double tap
+--[[--
+Handles both single and double tap.
--]]
function GestureDetector:tapState(tev)
logger.dbg("in tap state...")
@@ -590,8 +599,8 @@ function GestureDetector:holdState(tev, hold)
end
end
---[[
- @brief change gesture's x and y coordinates according to screen view mode
+--[[--
+ Changes gesture's `x` and `y` coordinates according to screen view mode.
@param ges gesture that you want to adjust
@return adjusted gesture.
diff --git a/frontend/document/documentregistry.lua b/frontend/document/documentregistry.lua
index 711981122..48bba2e84 100644
--- a/frontend/document/documentregistry.lua
+++ b/frontend/document/documentregistry.lua
@@ -1,8 +1,9 @@
-local logger = require("logger")
-
---[[
+--[[--
This is a registry for document providers
]]--
+
+local logger = require("logger")
+
local DocumentRegistry = {
registry = {},
providers = {},
@@ -12,6 +13,9 @@ function DocumentRegistry:addProvider(extension, mimetype, provider)
table.insert(self.providers, { extension = extension, mimetype = mimetype, provider = provider })
end
+--- Returns the registered document handler.
+-- @string file
+-- @treturn string provider, or nil
function DocumentRegistry:getProvider(file)
-- TODO: some implementation based on mime types?
for _, provider in ipairs(self.providers) do
diff --git a/frontend/ui/menusorter.lua b/frontend/ui/menusorter.lua
index 073aa86ae..72a63f51f 100644
--- a/frontend/ui/menusorter.lua
+++ b/frontend/ui/menusorter.lua
@@ -42,6 +42,10 @@ function MenuSorter:mergeAndSort(config_prefix, item_table, order)
return self:sort(item_table, order)
end
+--- Sorts a flat table of menu items into a hierarchical menu based on supplied order.
+---- @tparam table item_table menu item table
+---- @tparam table order sorting order
+---- @treturn table the sorted menu item table
function MenuSorter:sort(item_table, order)
local menu_table = {}
local sub_menus = {}
@@ -145,8 +149,8 @@ function MenuSorter:sort(item_table, order)
end
--- Returns a menu item by ID.
----- @param tbl Lua table
----- @param needle_id Menu item ID string
+---- @tparam table tbl Lua table
+---- @tparam string needle_id Menu item ID string
---- @treturn table a reference to the table item if found
function MenuSorter:findById(tbl, needle_id)
local items = {}
diff --git a/frontend/ui/translator.lua b/frontend/ui/translator.lua
index 1a639e2ce..2c945eacb 100644
--- a/frontend/ui/translator.lua
+++ b/frontend/ui/translator.lua
@@ -1,11 +1,12 @@
-local JSON = require("json")
-local logger = require("logger")
+--[[--
+This module translates text using Google Translate.
---[[
--- Translate text using Google Translate.
--- http://translate.google.com/translate_a/t?client=z&ie=UTF-8&oe=UTF-8&hl=en&tl=en&text=hello
+
--]]
+local JSON = require("json")
+local logger = require("logger")
+
local Translator = {
trans_servers = {
"http://translate.google.cn",
@@ -27,8 +28,13 @@ function Translator:getTransServer()
return G_reader_settings:readSetting("trans_server") or self.trans_servers[1]
end
---[[
--- return decoded JSON table from translate server
+--[[--
+Returns decoded JSON table from translate server.
+
+@string target_lang
+@string source_lang
+@string text
+@treturn string result, or nil
--]]
function Translator:loadPage(target_lang, source_lang, text)
local socket = require('socket')
@@ -80,6 +86,12 @@ function Translator:loadPage(target_lang, source_lang, text)
end
end
+--[[--
+Tries to automatically detect language of `text`.
+
+@string text
+@treturn string lang (`"en"`, `"fr"`, `…`)
+--]]
function Translator:detect(text)
local result = self:loadPage("en", nil, text)
if result then