diff --git a/html/ldoc_ltp.lua b/html/ldoc_ltp.lua
index a9c722d..9404f6d 100644
--- a/html/ldoc_ltp.lua
+++ b/html/ldoc_ltp.lua
@@ -90,6 +90,15 @@ return [==[
 # elseif module then -- module documentation
 <p>$(M(module.summary,module))</p>
 <p>$(M(module.description,module))</p>
+#   if module.usage then
+#     local li,il = use_li(module.usage)
+    <h3>Usage:</h3>
+    <ul>
+#     for usage in iter(module.usage) do
+        $(li)<pre class="example">$(usage)</pre>$(il)
+#     end -- for
+    </ul>
+#   end -- if usage
 
 # if not ldoc.no_summary then
 # -- bang out the tables of item types for this module (e.g Functions, Tables, etc)
diff --git a/ldoc.lua b/ldoc.lua
index 565729f..acd9fe7 100644
--- a/ldoc.lua
+++ b/ldoc.lua
@@ -58,7 +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')
+ModuleMap:add_kind('annotation','Issues')
 
 
 class.ProjectMap(KindMap)
diff --git a/ldoc/doc.lua b/ldoc/doc.lua
index e395b6a..d71c668 100644
--- a/ldoc/doc.lua
+++ b/ldoc/doc.lua
@@ -73,13 +73,16 @@ known_tags._annotation_tags = {
 local acount = 1
 
 function doc.expand_annotation_item (tags, last_item)
-   local tag, value = next(tags)
-   if known_tags._annotation_tags[tag] then
-      tags.class = 'annotation'
-      tags.summary = value
-      local item_name = last_item and last_item.tags.name or '?'
-      tags.name = item_name..'-'..tag..acount
-      acount = acount + 1
+   if tags.summary ~= '' then return false end
+   for tag, value in pairs(tags) do
+      if known_tags._annotation_tags[tag] then
+         tags.class = 'annotation'
+         tags.summary = value
+         local item_name = last_item and last_item.tags.name or '?'
+         tags.name = item_name..'-'..tag..acount
+         acount = acount + 1
+         return true
+      end
    end
 end
 
diff --git a/ldoc/parse.lua b/ldoc/parse.lua
index c89b95b..a4508b8 100644
--- a/ldoc/parse.lua
+++ b/ldoc/parse.lua
@@ -16,7 +16,8 @@ local tnext, append = lexer.skipws, table.insert
 
 -- a pattern particular to LuaDoc tag lines: the line must begin with @TAG,
 -- followed by the value, which may extend over several lines.
-local luadoc_tag = '^%s*@(%a+)%s(.+)'
+local luadoc_tag = '^%s*@(%a+)'
+local luadoc_tag_value = luadoc_tag..'(.*)'
 
 -- assumes that the doc comment consists of distinct tag lines
 function parse_tags(text)
@@ -25,7 +26,7 @@ function parse_tags(text)
    local tag_items = {}
    local follows
    while line do
-      local tag,rest = line:match(luadoc_tag)
+      local tag,rest = line:match(luadoc_tag_value)
       follows, line = tools.grab_while_not(lines,luadoc_tag)
       append(tag_items,{tag, rest .. '\n' .. follows})
    end
@@ -56,6 +57,7 @@ local function extract_tags (s)
       tag = Item.check_tag(tags,tag)
       value = strip(value)
       local old_value = tags[tag]
+
       if old_value then
          if type(old_value)=='string' then tags[tag] = List{old_value} end
          tags[tag]:append(value)