Docs: cosmetic updates and additions

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

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 = {}

frontend/ui/translator.lua

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