Doc: miscellaneous improvements.

frontend/optmath.lua

@@ -45,17 +45,23 @@ local function tmin_max(tab, func, op)
     return index, value
 end
 
---[[
-Return the minimum element of a table.
+--[[--
+Returns the minimum element of a table.
 The optional argument func specifies a one-argument ordering function.
+
+@tparam tab
+@tparam func
 ]]--
 function Math.tmin(tab, func)
     return tmin_max(tab, func, "min")
 end
 
---[[
-Return the maximum element of a table.
+--[[--
+Returns the maximum element of a table.
 The optional argument func specifies a one-argument ordering function.
+
+@tparam tab
+@tparam func
 ]]--
 function Math.tmax(tab, func)
     return tmin_max(tab, func, "max")

frontend/ui/geometry.lua

@@ -39,7 +39,7 @@ function Geom:new(o)
 end
 
 --[[--
-Make a deep copy of itself.
+Makes a deep copy of itself.
 @treturn Geom
 ]]
 function Geom:copy()
@@ -56,7 +56,7 @@ function Geom:__tostring()
 end
 
 --[[--
-Offset rectangle or point by relative values
+Offsets rectangle or point by relative values
 @int dx x delta
 @int dy y delta
 ]]
@@ -190,7 +190,7 @@ function Geom:intersect(rect_b)
 end
 
 --[[--
-Return true if self does not share any area with rect_b
+Returns true if self does not share any area with rect_b
 
 @tparam Geom rect_b
 ]]
@@ -205,7 +205,7 @@ function Geom:notIntersectWith(rect_b)
 end
 
 --[[--
-Return true if self geom shares area with rect_b
+Returns true if self geom shares area with rect_b.
 
 @tparam Geom rect_b
 ]]
@@ -214,7 +214,7 @@ function Geom:intersectWith(rect_b)
 end
 
 --[[--
-Set size of dimension or rectangle to size of given dimension/rectangle
+Set size of dimension or rectangle to size of given dimension/rectangle.
 
 @tparam Geom rect_b
 ]]
@@ -225,9 +225,9 @@ function Geom:setSizeTo(rect_b)
 end
 
 --[[--
-Check whether rect_b is within current rectangle
+Checks whether rect_b is within current rectangle
 
-Works for dimensions, too. For points, it is basically an equality check
+Works for dimensions, too. For points, it is basically an equality check.
 
 @tparam Geom rect_b
 ]]
@@ -243,9 +243,9 @@ function Geom:contains(rect_b)
 end
 
 --[[--
-Check for equality
+Checks for equality.
 
-Works for rectangles, points, dimensions
+Works for rectangles, points, and dimensions.
 
 @tparam Geom rect_b
 ]]
@@ -260,7 +260,7 @@ function Geom:__eq(rect_b)
 end
 
 --[[--
-Check size of dimension/rectangle for equality
+Checks the size of a dimension/rectangle for equality.
 
 @tparam Geom rect_b
 ]]
@@ -272,7 +272,7 @@ function Geom:equalSize(rect_b)
 end
 
 --[[--
-Check if our size is smaller than the size of the given dimension/rectangle
+Checks if our size is smaller than the size of the given dimension/rectangle.
 
 @tparam Geom rect_b
 ]]
@@ -284,7 +284,7 @@ function Geom:__lt(rect_b)
 end
 
 --[[--
-Check if our size is smaller or equal the size of the given dimension/rectangle
+Checks if our size is smaller or equal to the size of the given dimension/rectangle.
 @tparam Geom rect_b
 ]]
 function Geom:__le(rect_b)
@@ -295,11 +295,11 @@ function Geom:__le(rect_b)
 end
 
 --[[--
-Offset the current rectangle by dx, dy while fitting it into the space
-of a given rectangle
+Offsets the current rectangle by dx, dy while fitting it into the space
+of a given rectangle.
 
 This can also be called with dx=0 and dy=0, which will fit the current
-rectangle into the given rectangle
+rectangle into the given rectangle.
 
 @tparam Geom rect_b
 @int dx
@@ -332,7 +332,7 @@ function Geom:offsetWithin(rect_b, dx, dy)
 end
 
 --[[--
-Center the current rectangle at position x and y of a given rectangle
+Centers the current rectangle at position x and y of a given rectangle.
 
 @tparam Geom rect_b
 @int dx
@@ -370,7 +370,7 @@ function Geom:shrinkInside(rect_b, dx, dy)
 end
 
 --[[--
-Return the Euclidean distance between two geoms
+Returns the Euclidean distance between two geoms.
 
 @tparam Geom rect_b
 ]]
@@ -379,7 +379,7 @@ function Geom:distance(geom)
 end
 
 --[[--
-Return the midpoint of two geoms
+Returns the midpoint of two geoms.
 
 @tparam Geom geom
 @treturn Geom
@@ -393,7 +393,7 @@ function Geom:midpoint(geom)
 end
 
 --[[--
-Return center point in this geom
+Returns the center point of this geom.
 @treturn Geom
 ]]
 function Geom:center()

frontend/ui/widget/container/inputcontainer.lua

@@ -1,10 +1,10 @@
 --[[--
-An InputContainer is an WidgetContainer that handles user input events including multi touches
+An InputContainer is a WidgetContainer that handles user input events including multi touches
 and key presses.
 
-See @{InputContainer:registerTouchZones} for example on how to listen for multi touch inputs.
+See @{InputContainer:registerTouchZones} for examples of how to listen for multi touch input.
 
-An example for listening on key press input event is this:
+This example illustrates how to listen for a key press input event:
 
     PanBy20 = {
         { "Shift", Input.group.Cursor },
@@ -19,8 +19,8 @@ An example for listening on key press input event is this:
     },
     Quit = { {"Home"} },
 
-It is suggested to reference configurable sequences from another table
-and store that table as configuration setting
+It is recommended to reference configurable sequences from another table
+and to store that table as a configuration setting.
 
 ]]
 
@@ -84,10 +84,10 @@ end
 
 Register touch zones into this InputContainer.
 
-See gesturedetector for list of supported gestures.
+See gesturedetector for a list of supported gestures.
 
 NOTE: You are responsible for calling self:@{updateTouchZonesOnScreenResize} with the new
-screen dimension whenever the screen is rotated or resized.
+screen dimensions whenever the screen is rotated or resized.
 
 @tparam table zones list of touch zones to register
 
@@ -98,7 +98,7 @@ test_widget:registerTouchZones({
     {
         id = "foo_tap",
         ges = "tap",
-        -- This binds handler to the full screen
+        -- This binds the handler to the full screen
         screen_zone = {
             ratio_x = 0, ratio_y = 0, ratio_w = 1, ratio_h = 1,
         },
@@ -110,7 +110,7 @@ test_widget:registerTouchZones({
     {
         id = "foo_swipe",
         ges = "swipe",
-        -- This binds handler to bottom half of the screen
+        -- This binds the handler to bottom half of the screen
         screen_zone = {
             ratio_x = 0, ratio_y = 0.5, ratio_w = 1, ratio_h = 0.5,
         },
@@ -168,9 +168,9 @@ function InputContainer:registerTouchZones(zones)
 end
 
 --[[--
-Update touch zones based on new screen dimension.
+Updates touch zones based on new screen dimensions.
 
-@tparam ui.geometry.Geom new_screen_dimen new screen dimension
+@tparam ui.geometry.Geom new_screen_dimen new screen dimensions
 ]]
 function InputContainer:updateTouchZonesOnScreenResize(new_screen_dimen)
     for _, tzone in ipairs(self._touch_zones) do
@@ -183,8 +183,8 @@ function InputContainer:updateTouchZonesOnScreenResize(new_screen_dimen)
 end
 
 --[[
-the following handler handles keypresses and checks if they lead to a command.
-if this is the case, we retransmit another event within ourselves
+Handles keypresses and checks if they lead to a command.
+If this is the case, we retransmit another event within ourselves.
 --]]
 function InputContainer:onKeyPress(key)
     for name, seq in pairs(self.key_events) do

frontend/ui/widget/listview.lua

@@ -1,5 +1,5 @@
 --[[--
-Widget compoent that handles pagination for a list of items.
+Widget component that handles pagination for a list of items.
 
 Example:
 
@@ -7,9 +7,9 @@ Example:
         height = 400,
         width = 200,
         page_update_cb = function(curr_page_num, total_pages)
-            -- This callback function will be called whenever there is a
-            -- page turn event triggered. You can use it to update information
-            -- on parent widget.
+            -- This callback function will be called whenever a page
+            -- turn event is triggered. You can use it to update
+            -- information on the parent widget.
         end,
         items = {
             FrameContainer:new{
@@ -33,7 +33,7 @@ Example:
     }
 
 Note that ListView is created mainly to be used as a building block for other
-widgets like NetworkSetting so they can share the same pagination code.
+widgets like NetworkSetting, so they can share the same pagination code.
 ]]
 
 local InputContainer = require("ui/widget/container/inputcontainer")

frontend/util.lua

@@ -1,11 +1,11 @@
 --[[--
-Miscellaneous helper functions for KOReader frontend.
+This module contains miscellaneous helper functions for the KOReader frontend.
 ]]
 
 local BaseUtil = require("ffi/util")
 local util = {}
 
---- Strip all punctuations and spaces in a string.
+--- Strips all punctuation and spaces from a string.
 ---- @string text the string to be stripped
 ---- @treturn string stripped text
 function util.stripePunctuations(text)
@@ -99,8 +99,8 @@ function util.lastIndexOf(string, ch)
 end
 
 
---- Split string into a list of UTF-8 chars.
----- @string text the string to be splitted.
+--- Splits string into a list of UTF-8 characters.
+---- @string text the string to be split.
 ---- @treturn table list of UTF-8 chars
 function util.splitToChars(text)
     local tab = {}
@@ -117,7 +117,7 @@ function util.splitToChars(text)
     return tab
 end
 
--- Test whether c is a CJK character
+-- Tests whether c is a CJK character
 function util.isCJKChar(c)
     return string.match(c, "[\228-\234][\128-\191].") == c
 end
@@ -127,9 +127,9 @@ function util.hasCJKChar(str)
     return string.match(str, "[\228-\234][\128-\191].") ~= nil
 end
 
---- Split text into a list of words, spaces and punctuations.
+--- Split texts into a list of words, spaces and punctuation.
 ---- @string text text to split
----- @treturn table list of words, spaces and punctuations
+---- @treturn table list of words, spaces and punctuation
 function util.splitToWords(text)
     local wlist = {}
     for word in util.gsplit(text, "[%s%p]+", true) do