fixes issue #62: keep LuaDoc compatibility, unless not_luadoc is explicitly set

ldoc.lua

@@ -185,7 +185,8 @@ 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', 'pretty', 'charset', 'plain',
-   'readme','all','manual_url', 'ignore', 'colon','boilerplate','merge', 'wrap',
+   'readme','all','manual_url', 'ignore', 'colon',
+   'boilerplate','merge', 'wrap', 'not_luadoc',
    'no_return_or_parms','no_summary','full_description','backtick_references', 'custom_see_handler',
 }
 ldoc_contents = tablex.makeset(ldoc_contents)
@@ -361,6 +362,7 @@ setup_package_base()
 
 override 'colon'
 override 'merge'
+override 'not_luadoc'
 
 if type(args.file) == 'table' then
    -- this can only be set from config file so we can assume it's already read

ldoc/doc.lua

@@ -388,14 +388,21 @@ function Item:add_to_description (rest)
    end
 end
 
+function Item:trailing_warning (kind,tag,rest)
+   if type(rest)=='string' and #rest > 0 then
+      Item.warning(self,kind.." tag: '"..tag..'" has trailing text; use no_luadoc=true\n'..rest)
+   end
+end
+
 function Item:set_tag (tag,value)
    local ttype = known_tags[tag]
+   local args = self.file.args
 
    if ttype == TAG_MULTI or ttype == TAG_MULTI_LINE then -- value is always a List!
       if getmetatable(value) ~= List then
          value = List{value}
       end
-      if ttype ~= TAG_MULTI_LINE then
+      if ttype ~= TAG_MULTI_LINE and args.not_luadoc then
          local last = value[#value]
          if type(last) == 'string' and last:match '\n' then
             local line,rest = last:match('([^\n]+)(.*)')
@@ -417,12 +424,20 @@ function Item:set_tag (tag,value)
       if value == nil then self:error("Tag without value: "..tag) end
       local id, rest = tools.extract_identifier(value)
       self.tags[tag] = id
-      self:add_to_description(rest)
+      if args.not_luadoc then
+         self:add_to_description(rest)
+      else
+         self:trailing_warning('id',tag,rest)
+      end
    elseif ttype == TAG_SINGLE then
       self.tags[tag] = value
    elseif ttype == TAG_FLAG then
       self.tags[tag] = true
-      self:add_to_description(value)
+      if args.not_luadoc then
+         self:add_to_description(value)
+      else
+         self:trailing_warning('flag',tag,value)
+      end
    else
       Item.warning(self,"unknown tag: '"..tag.."' "..tostring(ttype))
    end

tests/styles/four.lua

@@ -1,8 +1,8 @@
 ------------
 -- Yet another module.
--- @module four
 -- Description can continue after simple tags, if you
--- like
+-- like - but to keep backwards compatibility, say 'not_luadoc=true'
+-- @module four
 -- @author bob, james
 -- @license MIT
 -- @copyright InfoReich 2013