1 -------------------------------------------------------------------------------
2 -- Handlers for several tags
3 -- @release $Id: tags.lua,v 1.8 2007/09/05 12:39:09 tomas Exp $
4 -------------------------------------------------------------------------------
6 local luadoc = require "luadoc"
7 local util = require "luadoc.util"
8 local string = require "string"
9 local table = require "table"
10 local assert, type, tostring, tonumber = assert, type, tostring, tonumber
12 module "luadoc.taglet.standard.tags"
14 -------------------------------------------------------------------------------
16 local function author (tag, block, text)
17 block[tag] = block[tag] or {}
19 luadoc.logger:warn("author `name' not defined [["..text.."]]: skipping")
22 table.insert (block[tag], text)
25 -------------------------------------------------------------------------------
26 -- Set the class of a comment block. Classes can be "module", "function",
27 -- "table". The first two classes are automatic, extracted from the source code
29 local function class (tag, block, text)
33 -------------------------------------------------------------------------------
35 local function cstyle (tag, block, text)
39 -------------------------------------------------------------------------------
41 local function sort (tag, block, text)
42 block[tag] = tonumber(text) or 0
45 -------------------------------------------------------------------------------
47 local function copyright (tag, block, text)
51 -------------------------------------------------------------------------------
53 local function description (tag, block, text)
57 -------------------------------------------------------------------------------
59 local function field (tag, block, text)
60 if block["class"] ~= "table" then
61 luadoc.logger:warn("documenting `field' for block that is not a `table'")
63 block[tag] = block[tag] or {}
65 local _, _, name, desc = string.find(text, "^([_%w%.]+)%s+(.*)")
66 assert(name, "field name not defined")
68 table.insert(block[tag], name)
69 block[tag][name] = desc
72 -------------------------------------------------------------------------------
73 -- Set the name of the comment block. If the block already has a name, issue
74 -- an error and do not change the previous value
76 local function name (tag, block, text)
77 if block[tag] and block[tag] ~= text then
78 luadoc.logger:error(string.format("block name conflict: `%s' -> `%s'", block[tag], text))
84 -------------------------------------------------------------------------------
85 -- Processes a parameter documentation.
86 -- @param tag String with the name of the tag (it must be "param" always).
87 -- @param block Table with previous information about the block.
88 -- @param text String with the current line being processed.
90 local function param (tag, block, text)
91 block[tag] = block[tag] or {}
92 -- TODO: make this pattern more flexible, accepting empty descriptions
93 local _, _, name, desc = string.find(text, "^([_%w%.]+)%s+(.*)")
95 luadoc.logger:warn("parameter `name' not defined [["..text.."]]: skipping")
98 local i = table.foreachi(block[tag], function (i, v)
104 luadoc.logger:warn(string.format("documenting undefined parameter `%s'", name))
105 table.insert(block[tag], name)
107 block[tag][name] = desc
110 -------------------------------------------------------------------------------
112 local function release (tag, block, text)
116 -------------------------------------------------------------------------------
118 local function ret (tag, block, text)
120 if type(block[tag]) == "string" then
121 block[tag] = { block[tag], text }
122 elseif type(block[tag]) == "table" then
123 table.insert(block[tag], text)
129 -------------------------------------------------------------------------------
132 local function see (tag, block, text)
133 -- see is always an array
134 block[tag] = block[tag] or {}
136 -- remove trailing "."
137 text = string.gsub(text, "(.*)%.$", "%1")
139 local s = util.split("%s*,%s*", text)
141 table.foreachi(s, function (_, v)
142 table.insert(block[tag], v)
146 -------------------------------------------------------------------------------
149 local function usage (tag, block, text)
150 if type(block[tag]) == "string" then
151 block[tag] = { block[tag], text }
152 elseif type(block[tag]) == "table" then
153 table.insert(block[tag], text)
159 -------------------------------------------------------------------------------
162 handlers["author"] = author
163 handlers["class"] = class
164 handlers["cstyle"] = cstyle
165 handlers["copyright"] = copyright
166 handlers["description"] = description
167 handlers["field"] = field
168 handlers["name"] = name
169 handlers["param"] = param
170 handlers["release"] = release
171 handlers["return"] = ret
172 handlers["see"] = see
173 handlers["sort"] = sort
174 handlers["usage"] = usage
176 -------------------------------------------------------------------------------
178 function handle (tag, block, text)
179 if not handlers[tag] then
180 luadoc.logger:error(string.format("undefined handler for tag `%s'", tag))
185 text = text:gsub("`([^\n]-)`", "<code>%1</code>")
186 text = text:gsub("`(.-)`", "<pre>%1</pre>")
189 -- assert(handlers[tag], string.format("undefined handler for tag `%s'", tag))
190 return handlers[tag](tag, block, text)