serious .0 bug squashed! nocolon option to turn off colon-style detection. boilerplate option forces first comments to be ignored

ldoc.lua

@@ -35,7 +35,7 @@ app.require_here()
 
 --- @usage
 local usage = [[
-ldoc, a documentation generator for Lua, vs 1.3.0
+ldoc, a documentation generator for Lua, vs 1.3.1
   -d,--dir (default docs) output directory
   -o,--output  (default 'index') output name
   -v,--verbose          verbose
@@ -53,6 +53,8 @@ ldoc, a documentation generator for Lua, vs 1.3.0
   -c,--config (default config.ld) configuration name
   -i,--ignore ignore any 'no doc comment or no module' warnings
   -D,--define (default none) set a flag to be used in config.ld
+  -N,--nocolon don't treat colons specially
+  -B,--boilerplate ignore first comment in source files
   --dump                debug output dump
   --filter (default none) filter output as Lua data (e.g pl.pretty.dump)
   --tags (default none) show all references to given tags, comma-separated
@@ -120,7 +122,7 @@ local ldoc = {}
 local add_language_extension
 
 local function override (field)
-   if ldoc[field] then args[field] = ldoc[field] end
+   if ldoc[field] ~= nil then args[field] = ldoc[field] end
 end
 
 -- aliases to existing tags can be defined. E.g. just 'p' for 'param'
@@ -178,7 +180,8 @@ end
 local ldoc_contents = {
    'alias','add_language_extension','new_type','add_section', 'tparam_alias',
    'file','project','title','package','format','output','dir','ext', 'topics',
-   'one','style','template','description','examples','readme','all','manual_url', 'ignore',
+   'one','style','template','description','examples',
+   'readme','all','manual_url', 'ignore', 'nocolon','boilerplate',
    'no_return_or_parms','no_summary','full_description','backtick_references', 'custom_see_handler',
 }
 ldoc_contents = tablex.makeset(ldoc_contents)
@@ -243,10 +246,11 @@ if args.module then
    if args.file:match '^%a+$' and global.functions[args.file] then
       args.file = 'global.'..args.file
    end
-   local fullpath,mod = tools.lookup_existing_module_or_function (args.file, doc_path)
+   local fullpath,mod,on_docpath = tools.lookup_existing_module_or_function (args.file, doc_path)
    if not fullpath then
       quit(mod)
    else
+      args.nocolon = on_docpath
       args.file = fullpath
       args.module = mod
    end
@@ -557,6 +561,8 @@ override 'output'
 override 'dir'
 override 'ext'
 override 'one'
+override 'nocolon'
+override 'boilerplate'
 
 if not args.ext:find '^%.' then
    args.ext = '.'..args.ext

ldoc/builtin/global.lua

@@ -19,7 +19,7 @@ function assert(v , message) end
 --   * "step": performs a garbage-collection step. The step "size" is controlled
 --   by `arg` (larger values mean more steps) in a non-specified way. If you
 --   want to control the step size you must experimentally tune the value of
---   * `arg`. Returns true if the step finished a collection cycle.
+--   * "arg". Returns true if the step finished a collection cycle.
 --   * "setpause": sets `arg` as the new value for the *pause* of the collector
 --   (see §2.10). Returns the previous value for *pause*.
 --   * "setstepmul": sets `arg` as the new value for the *step multiplier*

ldoc/html.lua

@@ -168,7 +168,9 @@ function html.generate_output(ldoc, args, project)
       ldoc.kinds_allowed = {module = true, topic = true}
    end
    ldoc.root = true
+   if ldoc.module then
       ldoc.module.info = get_module_info(ldoc.module)
+   end
    local out,err = template.substitute(module_template,{
       ldoc = ldoc,
       module = ldoc.module,

ldoc/parse.lua

@@ -93,10 +93,10 @@ end
 -- mark, and everything else in the preamble is the description.
 -- If a tag appears more than once, then its value becomes a list of strings.
 -- Alias substitution and @TYPE NAME shortcutting is handled by Item.check_tag
-local function extract_tags (s)
+local function extract_tags (s,args)
    local preamble,tag_items
    if s:match '^%s*$' then return {} end
-   if s:match ':%s' and not s:match '@%a' then
+   if not args.nocolon and s:match ':%s' and not s:match '@%a' then
       preamble,tag_items = parse_colon_tags(s)
    else
       preamble,tag_items = parse_at_tags(s)
@@ -183,7 +183,11 @@ local function parse_file(fname, lang, package, args)
 
    local mod
    local t,v = tnext(tok)
-   if t == '#' then
+   -- with some coding styles first comment is standard boilerplate; option to ignore this.
+   if args.boilerplate and t == 'comment' then
+      t,v = tnext(tok)
+   end
+   if t == '#' then -- skip Lua shebang line, if present
       while t and t ~= 'comment' do t,v = tnext(tok) end
       if t == nil then
          F:warning('empty file')
@@ -243,7 +247,7 @@ local function parse_file(fname, lang, package, args)
                item_follows, is_local, case = lang:item_follows(t,v,tok)
             end
             if item_follows or comment:find '@' or comment:find ': ' then
-               tags = extract_tags(comment)
+               tags = extract_tags(comment,args)
                if doc.project_level(tags.class) then
                   module_found = tags.name
                end
@@ -284,7 +288,7 @@ local function parse_file(fname, lang, package, args)
                -- we have to guess the module name
                module_found = tools.this_module_name(package,fname)
             end
-            if not tags then tags = extract_tags(comment) end
+            if not tags then tags = extract_tags(comment,args) end
             add_module(tags,module_found,old_style)
             tags = nil
             if not t then

ldoc/tools.lua

@@ -249,16 +249,18 @@ end
 
 function M.lookup_existing_module_or_function (name, docpath)
    -- first look up on the Lua module path
+   local on_docpath
    local fullpath, mod = M.find_existing_module(name,name,path.package_path)
    -- no go; but see if we can find it on the doc path
    if not fullpath then
       fullpath, mod = M.find_existing_module("ldoc.builtin." .. name,name,path.package_path)
+      on_docpath = true
 --~       fullpath, mod = M.find_existing_module(name, function(name)
 --~          local fpath = package.searchpath(name,docpath)
 --~          return fpath,true  -- result must always be 'lua'!
 --~       end)
    end
-   return fullpath, mod -- `mod` can be the error message
+   return fullpath, mod, on_docpath -- `mod` can be the error message
 end
 
 

tests/styles/x.c

@@ -1,4 +1,5 @@
-/* First comment is ignored,
+/***************
+ * First comment is ignored,
  * containing licenses, warnings,
  * old-fashioned commit info and so forth
  */