build/luadoc/luadoc/taglet/standard/tags.lua

   1 -------------------------------------------------------------------------------
   2 -- Handlers for several tags
   3 -- @release $Id: tags.lua,v 1.8 2007/09/05 12:39:09 tomas Exp $
   4 -------------------------------------------------------------------------------
   5
   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
  11
  12 module "luadoc.taglet.standard.tags"
  13
  14 -------------------------------------------------------------------------------
  15
  16 local function author (tag, block, text)
  17         block[tag] = block[tag] or {}
  18         if not text then
  19                 luadoc.logger:warn("author `name' not defined [["..text.."]]: skipping")
  20                 return
  21         end
  22         table.insert (block[tag], text)
  23 end
  24
  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
  28
  29 local function class (tag, block, text)
  30         block[tag] = text
  31 end
  32
  33 -------------------------------------------------------------------------------
  34
  35 local function cstyle (tag, block, text)
  36         block[tag] = text
  37 end
  38
  39 -------------------------------------------------------------------------------
  40
  41 local function sort (tag, block, text)
  42         block[tag] = tonumber(text) or 0
  43 end
  44
  45 -------------------------------------------------------------------------------
  46
  47 local function copyright (tag, block, text)
  48         block[tag] = text
  49 end
  50
  51 -------------------------------------------------------------------------------
  52
  53 local function description (tag, block, text)
  54         block[tag] = text
  55 end
  56
  57 -------------------------------------------------------------------------------
  58
  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'")
  62         end
  63         block[tag] = block[tag] or {}
  64
  65         local _, _, name, desc = string.find(text, "^([_%w%.]+)%s+(.*)")
  66         assert(name, "field name not defined")
  67
  68         table.insert(block[tag], name)
  69         block[tag][name] = desc
  70 end
  71
  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
  75
  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))
  79         end
  80
  81         block[tag] = text
  82 end
  83
  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.
  89
  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+(.*)")
  94         if not name then
  95                 luadoc.logger:warn("parameter `name' not defined [["..text.."]]: skipping")
  96                 return
  97         end
  98         local i = table.foreachi(block[tag], function (i, v)
  99                 if v == name then
 100                         return i
 101                 end
 102         end)
 103         if i == nil then
 104                 luadoc.logger:warn(string.format("documenting undefined parameter `%s'", name))
 105                 table.insert(block[tag], name)
 106         end
 107         block[tag][name] = desc
 108 end
 109
 110 -------------------------------------------------------------------------------
 111
 112 local function release (tag, block, text)
 113         block[tag] = text
 114 end
 115
 116 -------------------------------------------------------------------------------
 117
 118 local function ret (tag, block, text)
 119         tag = "ret"
 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)
 124         else
 125                 block[tag] = text
 126         end
 127 end
 128
 129 -------------------------------------------------------------------------------
 130 -- @see ret
 131
 132 local function see (tag, block, text)
 133         -- see is always an array
 134         block[tag] = block[tag] or {}
 135
 136         -- remove trailing "."
 137         text = string.gsub(text, "(.*)%.$", "%1")
 138
 139         local s = util.split("%s*,%s*", text)
 140
 141         table.foreachi(s, function (_, v)
 142                 table.insert(block[tag], v)
 143         end)
 144 end
 145
 146 -------------------------------------------------------------------------------
 147 -- @see ret
 148
 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)
 154         else
 155                 block[tag] = text
 156         end
 157 end
 158
 159 -------------------------------------------------------------------------------
 160
 161 local handlers = {}
 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
 175
 176 -------------------------------------------------------------------------------
 177
 178 function handle (tag, block, text)
 179         if not handlers[tag] then
 180                 luadoc.logger:error(string.format("undefined handler for tag `%s'", tag))
 181                 return
 182         end
 183
 184         if text then
 185                 text = text:gsub("`([^\n]-)`", "<code>%1</code>")
 186                 text = text:gsub("`(.-)`", "<pre>%1</pre>")
 187         end
 188
 189 --      assert(handlers[tag], string.format("undefined handler for tag `%s'", tag))
 190         return handlers[tag](tag, block, text)
 191 end