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
This commit is contained in:
parent
1bb83924bb
commit
9021b144b8
43
docs/doc.md
43
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
|
||||
string`.
|
||||
- `tparam_alias(name,type)` for instance, you may wish that `Object` means `@\tparam
|
||||
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
|
||||
|
||||
|
|
2
ldoc.lua
2
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)
|
||||
--
|
||||
|
|
19
ldoc/doc.lua
19
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 type(last) == 'string' and last:match '\n' then
|
||||
local line,rest = last:match('([^\n]+)(.*)')
|
||||
value[#value] = line
|
||||
self:add_to_description(rest)
|
||||
if ttype ~= TAG_MULTI_LINE then
|
||||
local last = value[#value]
|
||||
if type(last) == 'string' and last:match '\n' then
|
||||
local line,rest = last:match('([^\n]+)(.*)')
|
||||
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
|
||||
|
|
|
@ -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
|
||||
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue