usage is now explicitly a multiline tag, so it is not considered part of the description. We are now ignoring Lua comments like so --- some text --- since they're commonly used to indicate logical sections - not for export

docs/doc.md

@@ -1,5 +1,7 @@
 # LDoc, a Lua Documentation Tool
 
+@lookup doc.md
+
 ## Introduction
 
 LDoc is a second-generation documentation tool that can be used as a replacement for
@@ -407,8 +409,34 @@ can define an alias for it, such as 'p'. This can also be specified in the confi
 LDoc will also work with C/C++ files, since extension writers clearly have the same
 documentation needs as Lua module writers.
 
+LDoc allows you to attach a _type_ to a parameter or return value
+
+    --- better mangler.
+    -- @tparam string name
+    -- @int max length
+    -- @treturn string mangled name
+    function strmangler(name,max)
+    ...
+    end
+
+`int` here is short for `tparam int` (see @{Tag_Modifiers})
+
+It's common for types to be optional, or have different types, so the type can be like
+'?int|string' which renders as '(int or string)', or '?int', which renders as
+'(optional int)'.
+
 LDoc gives the documenter the option to use Markdown to parse the contents of comments.
 
+Since 1.3, LDoc allows the use of _colons_ instead of @.
+
+    --- a simple function.
+    -- string name person's name
+    -- int: age age of person
+    -- treturn: ?nil|string
+    -- function check(name,age)
+
+
+
 ## Adding new Tags
 
 LDoc tries to be faithful to LuaDoc, but provides some extensions. Aliases for tags can be
@@ -796,7 +824,7 @@ Like all good Github projects, Winapi has a `readme.md`:
 This goes under the 'Topics' global section; the 'Contents' of this document is generated
 from the second-level (##) headings of the readme.
 
-Readme files are always processed with Markdown, but may also contain @\{} references back
+Readme files are always processed with the current Markdown processor, but may also contain @\{} references back
 to the documentation and to example files. Any symbols within backticks will be expanded as
 references, if possible. As with doc comments, a link to a standard Lua function like
 @\{os.execute} will work as well. Any code sections will be pretty-printed as Lua, unless
@@ -823,6 +851,9 @@ the @lookup directive in documents, which must start at the first column on its
 For instance, if I am talking about `pl.utils`, then I can say "@lookup utils" and
 thereafter references like @\{printf} will resolve correctly.
 
+If you look at the source for this document, you will see a `@lookup doc.md` which allows
+direct references to sections like @{Readme_files|this}.
+
 Remember that the default is for references in backticks to be resolved; unlike @
 references, it is not an error if the reference cannot be found.
 
@@ -907,7 +938,8 @@ These only appear in `config.ld`:
   - `backtick_references` whether references in backticks will be resolved
   -  `manual_url` point to an alternative or local location for the Lua manual, e.g.
 'file:///D:/dev/lua/projects/lua-5.1.4/doc/manual.html'
-
+  - `one` use a one-column output format
+  - `no_summary` suppress the Contents summary
 
 Available functions are:
 
@@ -918,8 +950,11 @@ an extension to be recognized as this language
   - `add_section`
   - `new_type(tag,header,project_level)` used to add new tags, which are put in their own
 section `header`. They may be 'project level'.
-  - `tparam_alias(name,type)` for instance, you may wish that `string` means `@\tparam
+  - `tparam_alias(name,type)` for instance, you may wish that `Object` means `@\tparam
-string`.
+Object`.
+  - `custom_see_handler(pattern,handler)`. If a reference matches `pattern`, then the
+extracted values will be passed to `handler`. It is expected to return link text
+and a suitable URI. (This match will happen before default processing.)
 
 ## Annotations and Searching for Tags
 

ldoc.lua

@@ -7,7 +7,7 @@
 --
 -- C/C++ support for Lua extensions is provided.
 --
--- Available from LuaRocks as 'ldoc' and as a [Zip file](http://stevedonovan.github.com/files/ldoc-1.2.0.zip)
+-- Available from LuaRocks as 'ldoc' and as a [Zip file](http://stevedonovan.github.com/files/ldoc-1.3.0.zip)
 --
 -- [Github Page](https://github.com/stevedonovan/ldoc)
 --

ldoc/doc.lua

@@ -12,7 +12,7 @@ local global = require 'ldoc.builtin.globals'
 local tools = require 'ldoc.tools'
 local split_dotted_name = tools.split_dotted_name
 
-local TAG_MULTI,TAG_ID,TAG_SINGLE,TAG_TYPE,TAG_FLAG = 'M','id','S','T','N'
+local TAG_MULTI,TAG_ID,TAG_SINGLE,TAG_TYPE,TAG_FLAG,TAG_MULTI_LINE = 'M','id','S','T','N','ML'
 
 -- these are the basic tags known to ldoc. They come in several varieties:
 --  - 'M' tags with multiple values like 'param' (TAG_MULTI)
@@ -21,7 +21,7 @@ local TAG_MULTI,TAG_ID,TAG_SINGLE,TAG_TYPE,TAG_FLAG = 'M','id','S','T','N'
 --  - 'N' tags which have no associated value, like 'local` (TAG_FLAG)
 --  - 'T' tags which represent a type, like 'function' (TAG_TYPE)
 local known_tags = {
-   param = 'M', see = 'M', usage = 'M', ['return'] = 'M', field = 'M', author='M';
+   param = 'M', see = 'M', usage = 'ML', ['return'] = 'M', field = 'M', author='M';
    class = 'id', name = 'id', pragma = 'id', alias = 'id', within = 'id',
    copyright = 'S', summary = 'S', description = 'S', release = 'S', license = 'S',
    fixme = 'S', todo = 'S', warning = 'S', raise = 'S',
@@ -376,15 +376,17 @@ end
 function Item:set_tag (tag,value)
    local ttype = known_tags[tag]
 
-   if ttype == TAG_MULTI then -- value is always a List!
+   if ttype == TAG_MULTI or ttype == TAG_MULTI_LINE then -- value is always a List!
       if getmetatable(value) ~= List then
          value = List{value}
       end
-      local last = value[#value]
+      if ttype ~= TAG_MULTI_LINE then
-      if type(last) == 'string' and last:match '\n' then
+         local last = value[#value]
-         local line,rest = last:match('([^\n]+)(.*)')
+         if type(last) == 'string' and last:match '\n' then
-         value[#value] = line
+            local line,rest = last:match('([^\n]+)(.*)')
-         self:add_to_description(rest)
+            value[#value] = line
+            self:add_to_description(rest)
+         end
       end
       self.tags[tag] = value
    elseif ttype == TAG_ID then
@@ -401,6 +403,7 @@ function Item:set_tag (tag,value)
       self.tags[tag] = value
    elseif ttype == TAG_FLAG then
       self.tags[tag] = true
+      self:add_to_description(value)
    else
       Item.warning(self,"unknown tag: '"..tag.."' "..tostring(ttype))
    end

ldoc/lang.lua

@@ -19,6 +19,9 @@ end
 
 function Lang:start_comment (v)
    local line = v:match (self.start_comment_)
+   if line and self.end_comment_ and v:match (self.end_comment_) then
+      return nil
+   end
    local block = v:match(self.block_comment)
    return line or block, block
 end
@@ -70,6 +73,7 @@ function Lua:_init()
    self.line_comment = '^%-%-+' -- used for stripping
    self.start_comment_ = '^%-%-%-+'     -- used for doc comment line start
    self.block_comment = '^%-%-%[=*%[%-+' -- used for block doc comments
+   self.end_comment_ = '[^%-]%-%-+\n$' ---- exclude --- this kind of comment ---
    self:finalize()
 end
 

ldoc/markup.lua

@@ -252,6 +252,9 @@ function markup.create (ldoc, format)
    global_context = ldoc.package and ldoc.package .. '.'
 
    markup.process_reference = function(name)
+      if local_context == 'none.' and not name:match '%.' then
+         return nil,'not found'
+      end
       local mod = ldoc.single or ldoc.module or ldoc.modules[1]
       local ref,err = mod:process_see_reference(name, ldoc.modules)
       if ref then return ref end