From e410ce14df4cefaed5a358a3f8e30fb679f65e4f Mon Sep 17 00:00:00 2001
From: Qingping Hou <dave2008713@gmail.com>
Date: Mon, 15 Feb 2016 16:14:15 -0800
Subject: [PATCH] doc: types/functions for font and rendertext module

---
 doc/config.ld              |  2 +-
 frontend/ui/font.lua       | 11 ++++++++++-
 frontend/ui/rendertext.lua | 25 +++++++++++++++++++++++--
 3 files changed, 34 insertions(+), 4 deletions(-)

diff --git a/doc/config.ld b/doc/config.ld
index 9f6ef8cf0..bd70251b1 100644
--- a/doc/config.ld
+++ b/doc/config.ld
@@ -8,5 +8,5 @@ use_markdown_titles = true
 readme = '../README.md'
 package = ''
 format = 'markdown'
-sort_modules=true
+sort_modules = true
 file = '../frontend'
diff --git a/frontend/ui/font.lua b/frontend/ui/font.lua
index 7930ffd9f..aa58db688 100644
--- a/frontend/ui/font.lua
+++ b/frontend/ui/font.lua
@@ -1,3 +1,7 @@
+--[[--
+Font module.
+]]
+
 local lfs = require("libs/libkoreader-lfs")
 local Freetype = require("ffi/freetype")
 local Screen = require("device").screen
@@ -82,6 +86,12 @@ function Font:getFace(font, size)
             DEBUG("#! Font "..font.." ("..realname..") not supported: "..face)
             return nil
         end
+        --- Freetype font face wrapper object
+        -- @table FontFaceObj
+        -- @field size size of the font face (after scaled by screen size)
+        -- @field orig_size raw size of the font face (before scale)
+        -- @field ftface font face object from freetype
+        -- @field hash hash key for this font face
         face_obj = {
             size = size,
             orig_size = orig_size,
@@ -89,7 +99,6 @@ function Font:getFace(font, size)
             hash = hash
         }
         self.faces[hash] = face_obj
-    -- DEBUG("getFace, found: "..realname.." size:"..size)
     end
     return face_obj
 end
diff --git a/frontend/ui/rendertext.lua b/frontend/ui/rendertext.lua
index fead79cf4..30d1e517a 100644
--- a/frontend/ui/rendertext.lua
+++ b/frontend/ui/rendertext.lua
@@ -1,3 +1,7 @@
+--[[--
+Text rendering module.
+]]
+
 local Font = require("ui/font")
 local Cache = require("cache")
 local CacheItem = require("cacheitem")
@@ -118,6 +122,18 @@ function RenderText:getSubTextByWidth(text, face, width, kerning, bold)
     return table.concat(char_list)
 end
 
+--- Measure rendered size for a given text.
+--
+-- Note this function does not render the text into a bitmap. Use it if you
+-- only care about the size for the rendered result.
+--
+---- @int x start position for a given text (within maxium width)
+---- @int width maxium rendering width (think of it as size of the bitmap)
+---- @tparam ui.font.FontFaceObj face font face that will be used for rendering
+---- @string text text to measure
+---- @bool[opt=false] kerning whether the text should be measured with kerning
+---- @bool[opt=false] bold whether the text should be measured as bold
+---- @treturn RenderTextSize
 function RenderText:sizeUtf8Text(x, width, face, text, kerning, bold)
     if not text then
         DEBUG("sizeUtf8Text called without text");
@@ -139,11 +155,16 @@ function RenderText:sizeUtf8Text(x, width, face, text, kerning, bold)
             pen_x = pen_x + glyph.ax
             pen_y_top = math.max(pen_y_top, glyph.t)
             pen_y_bottom = math.max(pen_y_bottom, glyph.bb:getHeight() - glyph.t)
-            --DEBUG("ax:"..glyph.ax.." t:"..glyph.t.." r:"..glyph.r.." h:"..glyph.bb:getHeight().." w:"..glyph.bb:getWidth().." yt:"..pen_y_top.." yb:"..pen_y_bottom)
             prevcharcode = charcode
         end -- if pen_x < (width - x)
     end
-    return { x = pen_x, y_top = pen_y_top, y_bottom = pen_y_bottom}
+
+    --- RenderText size information
+    -- @table RenderTextSize
+    -- @field x length of the text on x coordinates
+    -- @field y_top top offset for the text (relative to center of the text)
+    -- @field y_bottom bottom offset for the text (relative to center of the text)
+    return { x = pen_x, y_top = pen_y_top, y_bottom = pen_y_bottom }
 end
 
 function RenderText:renderUtf8Text(buffer, x, y, face, text, kerning, bold, fgcolor, width)