From 014c003a1ae4293f1442d389bacdf034d7423c0c Mon Sep 17 00:00:00 2001
From: steve donovan <steve.j.donovan@gmail.com>
Date: Wed, 8 Jun 2011 19:12:04 +0200
Subject: [PATCH] sections may now have associated descriptions

---
 doc.lua   |  5 +++--
 ldoc.ltp  |  1 +
 tools.lua | 17 ++++++++++++-----
 3 files changed, 16 insertions(+), 7 deletions(-)

diff --git a/doc.lua b/doc.lua
index 63c7701..ec30eaf 100644
--- a/doc.lua
+++ b/doc.lua
@@ -141,12 +141,14 @@ function File:finish()
             end
 
             -- right, this item was within a section or a 'class'
+            local section_description
             if this_mod.section then
                item.section = this_mod.section.display_name
                -- if it was a class, then the name should be 'Class.foo'
                if this_mod.section.type == 'type' then
                   item.name = this_mod.section.name .. '.' .. item.name
                end
+               section_description = this_mod.section.description
             else -- otherwise, just goes into the default sections (Functions,Tables,etc)
                item.section = item.type
             end
@@ -156,9 +158,8 @@ function File:finish()
             these_items.by_name[item.name] = item
             these_items:append(item)
 
-
             -- register this item with the iterator
-            this_mod.kinds:add(item,these_items)
+            this_mod.kinds:add(item,these_items,section_description)
 
          else
             -- must be a free-standing function (sometimes a problem...)
diff --git a/ldoc.ltp b/ldoc.ltp
index 6e6103f..103b029 100644
--- a/ldoc.ltp
+++ b/ldoc.ltp
@@ -102,6 +102,7 @@
 # --- function parameters or table fields.
 # for kind, items in module.kinds() do
     <h2><a name="$(no_spaces(kind))"></a>$(kind)</h2>
+    $(M(module.kinds:get_section_description(kind)))
     <dl class="function">
 #  for item in items() do
     <dt>
diff --git a/tools.lua b/tools.lua
index 1d810e6..6f87f07 100644
--- a/tools.lua
+++ b/tools.lua
@@ -44,8 +44,8 @@ end
 local KindMap = class()
 M.KindMap = KindMap
 
--- calling a KindMap returns an iterator. This returns the kind and the iterator
--- over the items of that type.
+-- calling a KindMap returns an iterator. This returns the kind, the iterator
+-- over the items of that type, and the actual type tag value.
 function KindMap:__call ()
    local i = 1
    local klass = self.klass
@@ -69,14 +69,20 @@ function KindMap:type_of (item)
    return klass.types_by_kind [kind]
 end
 
+function KindMap:get_section_description (kind)
+    return self.klass.descriptions[kind]
+end
+
 -- called for each new item. It does not actually create separate lists,
 -- (although that would not break the interface) but creates iterators
 -- for that item type if not already created.
-function KindMap:add (item,items)
-   local group = item[self.fieldname]
-   local kname = self.klass.types_by_tag[group]
+function KindMap:add (item,items,description)
+   local group = item[self.fieldname] -- which wd be item's type or section
+   local kname = self.klass.types_by_tag[group] -- the kind name
    if not self[kname] then
       self[kname] = M.type_iterator (items,self.fieldname,group)
+      --print(kname,description)
+      self.klass.descriptions[kname] = description
    end
 end
 
@@ -86,6 +92,7 @@ function KindMap._class_init (klass)
    klass.kinds = {} -- list in correct order of kinds
    klass.types_by_tag = {} -- indexed by tag
    klass.types_by_kind = {} -- indexed by kind
+   klass.descriptions = {} -- optional description for each kind
 end