@type summary no longer dropped (#49); @type can be used with @usage (#52); CSS tweaks for prettification; nasty '<pre/>' typo squashed

ldoc/doc.lua

@@ -194,7 +194,7 @@ function File:finish()
    local function add_section (item, display_name)
       display_name = display_name or item.display_name
       this_mod.section = item
-      this_mod.kinds:add_kind(display_name,display_name)
+      this_mod.kinds:add_kind(display_name,display_name,nil,item)
       this_mod.sections:append(item)
       this_mod.sections.by_name[display_name:gsub('%A','_')] = item
    end
@@ -314,7 +314,7 @@ function File:finish()
                      end
                   end
                end
-               section_description = this_section.description
+               section_description = this_section.summary..' '..this_section.description
             elseif item.tags.within then
                section_description = item.tags.within
                item.section = section_description

ldoc/html.lua

@@ -64,6 +64,11 @@ function html.generate_output(ldoc, args, project)
       return prettify.code('lua','usage',str,0,false)
    end
 
+   -- Item descriptions come from combining the summary and description fields
+   function ldoc.descript(item)
+      return (item.summary or '?')..' '..(item.description or '')
+   end
+
    -- this generates the internal module/function references
    function ldoc.href(see)
       if see.href then -- explict reference, e.g. to Lua manual

ldoc/html/ldoc_css.lua

@@ -283,14 +283,6 @@ ol ol { margin-top: 0px; }
 ul ol { margin-top: 0px; }
 
 /* styles for prettification of source */
-/*
-.keyword {font-weight: bold; color: #6666AA; }
-.number  { color: #AA6666; }
-.string  { color: #8888AA; }
-.comment { color: #666600; }
-.prepro { color: #006666; }
-.global { color: #800080; }
-*/
 pre .comment { color: #558817; }
 pre .constant { color: #a8660d; }
 pre .escape { color: #844631; }
@@ -298,9 +290,10 @@ pre .keyword { color: #2239a8; font-weight: bold; }
 pre .library { color: #0e7c6b; }
 pre .marker { color: #512b1e; background: #fedc56; font-weight: bold; }
 pre .string { color: #a8660d; }
-pre .number { color: #a8660d; }
+pre .number { color: #f8660d; }
 pre .operator { color: #2239a8; font-weight: bold; }
 pre .preprocessor, pre .prepro { color: #a33243; }
+pre .global { color: #800080; }
 pre .prompt { color: #558817; }
 pre .url { color: #272fc2; text-decoration: underline; }
 ]==]

ldoc/html/ldoc_ltp.lua

@@ -135,8 +135,16 @@ return [==[
 # local show_return = not ldoc.no_return_or_parms
 # local show_parms = show_return
 # for kind, items in module.kinds() do
+#   local kitem = module.kinds:get_item(kind)
     <h2><a name="$(no_spaces(kind))"></a>$(kind)</h2>
-    $(M(module.kinds:get_section_description(kind),nil))
+#--    $(M(module.kinds:get_section_description(kind),nil))
+#   if kitem then
+        $(M(ldoc.descript(kitem),kitem))
+#       if kitem.usage then
+            <h3>Usage:</h3>
+            <pre class="example">$(ldoc.prettify(kitem.usage[1]))</pre>
+#        end
+#   end
     <dl class="function">
 #  for item in items() do
     <dt>
@@ -144,7 +152,7 @@ return [==[
     <strong>$(display_name(item))</strong>
     </dt>
     <dd>
-    $(M((item.summary or '?')..' '..(item.description or ''),item))
+    $(M(ldoc.descript(item),item))
 
 #  if show_parms and item.params and #item.params > 0 then
     <h3>$(module.kinds:type_of(item).subnames):</h3>

ldoc/prettify.lua

@@ -61,7 +61,7 @@ function prettify.lua (fname, code, initial_lineno, pre)
       res[#res] = last:gsub('\n+','')
    end
    if pre then
-      res:append '<pre/>\n'
+      res:append '</pre>\n'
    end
    return res:join ()
 end

ldoc/tools.lua

@@ -90,6 +90,10 @@ function KindMap:get_section_description (kind)
    return self.klass.descriptions[kind]
 end
 
+function KindMap:get_item (kind)
+   return self.klass.items_by_kind[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.
@@ -110,13 +114,17 @@ function KindMap._class_init (klass)
    klass.types_by_tag = {} -- indexed by tag
    klass.types_by_kind = {} -- indexed by kind
    klass.descriptions = {} -- optional description for each kind
+   klass.items_by_kind = {}  -- some kinds are items
 end
 
 
-function KindMap.add_kind (klass,tag,kind,subnames)
+function KindMap.add_kind (klass,tag,kind,subnames,item)
    if not klass.types_by_kind[kind] then
       klass.types_by_tag[tag] = kind
       klass.types_by_kind[kind] = {type=tag,subnames=subnames}
+      if item then
+         klass.items_by_kind[kind] = item
+      end
       append(klass.kinds,kind)
    end
 end

tests/usage/config.ld

@@ -1,5 +1,10 @@
 project = 'usage'
 file = 'usage.lua'
+examples='usage.lua'
+-- can specify both the Markdown processor
+-- and the prettifier - this will use lxsh if available
 format='markdown'
+pretty='lxsh'
+-- suppress @params and the summary at the top
 no_return_or_parms=true
 no_summary=true

tests/usage/usage.lua

@@ -7,7 +7,12 @@ A simple module with examples.
 local usage = {}
 
 ----------
--- A simple vector class
+-- A simple vector class.
+--
+-- Supports arithmetic operations.
+-- @usage
+-- v = Vector.new {10,20,30}
+-- assert (v == Vector{10,20,30})
 -- @type Vector
 
 local Vector = {}
@@ -15,6 +20,7 @@ usage.Vector = {}
 
 ----------
 -- Create a vector from an array `t`.
+-- `Vector` is also callable!
 function Vector.new (t)
 end
 
@@ -26,6 +32,11 @@ end
 function Vector.parse (s)
 end
 
+--------
+-- Compare two vectors for equality.
+function Vector:__eq (v)
+end
+
 ----------
 -- Add another vector, array or scalar `v` to this vector.
 -- Returns new `Vector`