From 11f55d2affca52ca03a491223823204f94c7ae90 Mon Sep 17 00:00:00 2001
From: Qingping Hou <dave2008713@gmail.com>
Date: Sun, 4 Dec 2016 16:41:01 -0800
Subject: [PATCH] doc: Event and WidgetContainer

---
 frontend/ui/event.lua                         | 22 ++++++++++++---
 .../ui/widget/container/widgetcontainer.lua   | 27 ++++++++++++-------
 2 files changed, 37 insertions(+), 12 deletions(-)

diff --git a/frontend/ui/event.lua b/frontend/ui/event.lua
index fcc20c93e..df3759edf 100644
--- a/frontend/ui/event.lua
+++ b/frontend/ui/event.lua
@@ -1,14 +1,30 @@
---[[
+--[[--
 Events are messages that are passed through the widget tree
 
 Events need a "name" attribute as minimal data.
 
 In order to see how event propagation works and how to make
-widgets event-aware see the implementation in WidgetContainer
-below.
+widgets event-aware see the implementation in @{ui.widget.container.widgetcontainer}.
+]]
+
+--[[--
+@field handler name for the handler method
+@field args array of arguments for the event
+@table Event
 ]]
 local Event = {}
 
+--[[--
+Create a new event.
+
+@string name
+@tparam[opt] ... arguments for the event
+@treturn Event
+
+@usage
+local Event = require("ui/event")
+Event:new("GotoPage", 1)
+]]
 function Event:new(name, ...)
     local o = {
         handler = "on"..name,
diff --git a/frontend/ui/widget/container/widgetcontainer.lua b/frontend/ui/widget/container/widgetcontainer.lua
index 1473412ab..801f746b8 100644
--- a/frontend/ui/widget/container/widgetcontainer.lua
+++ b/frontend/ui/widget/container/widgetcontainer.lua
@@ -1,3 +1,9 @@
+--[[--
+WidgetContainer is a container for another Widget. Base class for all the widget containers.
+
+It handles event propagation and paiting (with different alignments) for its children.
+]]
+
 local Geom = require("ui/geometry")
 local Widget = require("ui/widget/widget")
 
@@ -5,9 +11,6 @@ if require("device"):isAndroid() then
     require("jit").off(true, true)
 end
 
---[[
-WidgetContainer is a container for another Widget
---]]
 local WidgetContainer = Widget:new()
 
 function WidgetContainer:init()
@@ -37,9 +40,9 @@ function WidgetContainer:getSize()
     end
 end
 
---[[
-delete all child widgets
---]]
+--[[--
+Delete all child widgets
+]]
 function WidgetContainer:clear()
     while table.remove(self) do end
 end
@@ -80,9 +83,15 @@ function WidgetContainer:propagateEvent(event)
     return false
 end
 
---[[
-Containers will pass events to children or react on them themselves
---]]
+--[[--
+WidgetContainer will pass event to its children by calling their handleEvent
+methods. If no child responded to the event (by returning true), it will call its own
+handleEvent method.
+
+@tparam ui.event.Event event
+@treturn bool true if event is consumed, othewise false. A consumed event will
+not be sent to other widgets.
+]]
 function WidgetContainer:handleEvent(event)
     if not self:propagateEvent(event) then
         -- call our own standard event handler