support for -- @usage shortcut

ldoc/lang.lua

@@ -55,6 +55,10 @@ end
 function Lang:parse_extra (tags,tok)
 end
 
+function Lang:parse_usage (tags, tok)
+   return nil, "@usage deduction not implemented for this language"
+end
+
 
 class.Lua(Lang)
 
@@ -172,6 +176,16 @@ function Lua:parse_extra (tags,tok)
    end
 end
 
+function Lua:parse_usage (tags, tok)
+   if tags.class ~= 'field' then return nil,"cannot deduce @usage" end
+   local t1= tnext(tok)
+   local t2 = tok()
+   if t1 ~= '[' or t1 ~= '[' then return nil, 'not a long string' end
+   t, v = tools.grab_block_comment('',tok,'%]%]')
+   return true, v
+end
+
+
 -- note a difference here: we scan C/C++ code in full-text mode, not line by line.
 -- This is because we can't detect multiline comments in line mode
 

ldoc/parse.lua

@@ -173,6 +173,18 @@ local function parse_file(fname,lang, package)
                -- then don't continue to do any code analysis!
                if tags.name then
                   item_follows, is_local = false, false
+                elseif tags.summary == '' and tags.usage then
+                  -- For Lua, a --- @usage comment means that a long
+                  -- string containing the usage follows, which we
+                  -- use to update the module usage tag
+                  item_follows(tags,tok)
+                  local res, value = lang:parse_usage(tags,tok)
+                  if not res then F:warning(fname,value,1); break
+                  else
+                     current_item.tags.usage = {value}
+                     -- don't continue to make an item!
+                     ldoc_comment = false
+                  end
                end
             end
          end