From f5c11dcdf5a9ab49b78044507d1d5f8a7a4bbf36 Mon Sep 17 00:00:00 2001
From: steve donovan <steve.j.donovan@gmail.com>
Date: Sat, 17 Sep 2011 19:13:47 +0200
Subject: [PATCH] support for annotations: an item containing one of fixme,
 todo or warning can appear anywhere in code

---
 ldoc.lua       |  1 +
 ldoc/doc.lua   | 26 ++++++++++++++++++++++++--
 ldoc/parse.lua |  3 +++
 3 files changed, 28 insertions(+), 2 deletions(-)

diff --git a/ldoc.lua b/ldoc.lua
index 70de1cd..b2efb00 100644
--- a/ldoc.lua
+++ b/ldoc.lua
@@ -58,6 +58,7 @@ ModuleMap:add_kind('function','Functions','Parameters')
 ModuleMap:add_kind('table','Tables','Fields')
 ModuleMap:add_kind('field','Fields')
 ModuleMap:add_kind('lfunction','Local Functions','Parameters')
+ModuleMap:add_kind('annotation','Annotations')
 
 
 class.ProjectMap(KindMap)
diff --git a/ldoc/doc.lua b/ldoc/doc.lua
index cd3a4e8..bc4d29c 100644
--- a/ldoc/doc.lua
+++ b/ldoc/doc.lua
@@ -20,7 +20,8 @@ local known_tags = {
    copyright = 'S', summary = 'S', description = 'S', release = 'S', license = 'S',
    fixme = 'S', todo = 'S', warning = 'S';
    module = 'T', script = 'T', example = 'T', topic = 'T', -- project-level
-   ['function'] = 'T', lfunction = 'T', table = 'T', section = 'T', type = 'T'; -- module-level
+   ['function'] = 'T', lfunction = 'T', table = 'T', section = 'T', type = 'T',
+   annotation = 'T'; -- module-level
    ['local'] = 'N';
 }
 known_tags._alias = {}
@@ -30,6 +31,9 @@ known_tags._project_level = {
    example = true,
    topic = true
 }
+known_tags._annotation_tags = {
+   fixme = true, todo = true, warning = true
+}
 
 local TAG_MULTI,TAG_ID,TAG_SINGLE,TAG_TYPE,TAG_FLAG = 'M','id','S','T','N'
 doc.TAG_MULTI,doc.TAG_ID,doc.TAG_SINGLE,doc.TAG_TYPE,doc.TAG_FLAG =
@@ -63,6 +67,23 @@ function doc.section_tag (tag)
    return tag == 'section' or tag == 'type'
 end
 
+-- is it an annotation tag, like fixme or todo?
+function doc.annotation_tag (tag)
+   return known_tags._annotation_tags[tag]
+end
+
+local acount = 1
+
+function doc.expand_annotation_item (tags)
+   local tag, value = next(tags)
+   if doc.annotation_tag(tag) then
+      tags.class = 'annotation'
+      tags.summary = value
+      tags.name = tag..acount
+      acount = acount+1
+   end
+end
+
 -- we process each file, resulting in a File object, which has a list of Item objects.
 -- Items can be modules, scripts ('project level') or functions, tables, etc.
 -- (In the code 'module' refers to any project level tag.)
@@ -403,11 +424,12 @@ function Module:resolve_references(modules)
    end
 end
 
--- suppress the display of local functions.
+-- suppress the display of local functions and annotations.
 -- This is just a placeholder hack until we have a more general scheme
 -- for indicating 'private' content of a module.
 function Module:mask_locals ()
    self.kinds['Local Functions'] = nil
+   self.kinds['Annotations'] = nil
 end
 
 function Item:dump_tags (taglist)
diff --git a/ldoc/parse.lua b/ldoc/parse.lua
index 50c3efb..42d06cc 100644
--- a/ldoc/parse.lua
+++ b/ldoc/parse.lua
@@ -165,6 +165,9 @@ local function parse_file(fname,lang, package)
                if doc.project_level(tags.class) then
                   module_found = tags.name
                end
+               doc.expand_annotation_item(tags)
+               -- if the item has an explicit name or defined meaning
+               -- then don't continue to do any code analysis!
                if tags.name then
                   item_follows, is_local = false, false
                end