Docs: cosmetic updates and additions

* Content from wiki had some cosmetic leftover glitches
* Added/adapted some docs for other modules

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/
+* [GitHub's blog post](https://github.com/blog/120-new-to-git)
-* http://sixrevisions.com/resources/git-tutorials-beginners/
+* <http://try.github.com/>
-* http://rogerdudler.github.io/git-guide/
+* <http://sixrevisions.com/resources/git-tutorials-beginners/>
+* <http://rogerdudler.github.io/git-guide/>
 
 ## Get latest code from the KOReader repository
 First you need to add the official repo to your remote repo list:

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`

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: <https://github.com/koreader/kindlepdfviewer/pull/475>
 
 
 ## Developing UI widgets ##

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
+  * 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)
-    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
+
+ * <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
 
+ * <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
-

frontend/device/gesturedetector.lua

@@ -1,46 +1,51 @@
-local Geom = require("ui/geometry")
+--[[--
-local TimeVal = require("ui/timeval")
+This module detects gestures.
-local logger = require("logger")
 
---[[
 Current detectable gestures:
-    * touch (user touched screen)
+
-    * tap (touch action detected as single tap)
+* `touch` (user touched screen)
-    * pan
+* `tap` (touch action detected as single tap)
-    * hold
+* `pan`
-    * swipe
+* `hold`
-    * pinch
+* `swipe`
-    * spread
+* `pinch`
-    * rotate
+* `spread`
-    * hold_pan
+* `rotate`
-    * double_tap
+* `hold_pan`
-    * inward_pan
+* `double_tap`
-    * outward_pan
+* `inward_pan`
-    * pan_release
+* `outward_pan`
-    * hold_release
+* `pan_release`
-    * two_finger_tap
+* `hold_release`
-    * two_finger_pan
+* `two_finger_tap`
-    * two_finger_swipe
+* `two_finger_pan`
-    * two_finger_pan_release
+* `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
+@{GestureDetector:feedEvent|GestureDetector:feedEvent(tev)} will return a
-feed a touch release event to it.
+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
+Compares `last_pan` with `first_tev` in this slot.
-return pan direction and distance
+
+@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.

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

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
+---- @tparam table tbl Lua table
----- @param needle_id Menu item ID string
+---- @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 = {}

frontend/ui/translator.lua

@@ -1,11 +1,12 @@
-local JSON = require("json")
+--[[--
-local logger = require("logger")
+This module translates 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>
--- 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