contrib/luadoc/lua/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 = assert, type, tostring
  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 copyright (tag, block, text)
  36         block[tag] = text
  37 end
  38
  39 -------------------------------------------------------------------------------
  40
  41 local function description (tag, block, text)
  42         block[tag] = text
  43 end
  44
  45 -------------------------------------------------------------------------------
  46
  47 local function field (tag, block, text)
  48         if block["class"] ~= "table" then
  49                 luadoc.logger:warn("documenting `field' for block that is not a `table'")
  50         end
  51         block[tag] = block[tag] or {}
  52
  53         local _, _, name, desc = string.find(text, "^([_%w%.]+)%s+(.*)")
  54         assert(name, "field name not defined")
  55
  56         table.insert(block[tag], name)
  57         block[tag][name] = desc
  58 end
  59
  60 -------------------------------------------------------------------------------
  61 -- Set the name of the comment block. If the block already has a name, issue
  62 -- an error and do not change the previous value
  63
  64 local function name (tag, block, text)
  65         if block[tag] and block[tag] ~= text then
  66                 luadoc.logger:error(string.format("block name conflict: `%s' -> `%s'", block[tag], text))
  67         end
  68
  69         block[tag] = text
  70 end
  71
  72 -------------------------------------------------------------------------------
  73 -- Processes a parameter documentation.
  74 -- @param tag String with the name of the tag (it must be "param" always).
  75 -- @param block Table with previous information about the block.
  76 -- @param text String with the current line beeing processed.
  77
  78 local function param (tag, block, text)
  79         block[tag] = block[tag] or {}
  80         -- TODO: make this pattern more flexible, accepting empty descriptions
  81         local _, _, name, desc = string.find(text, "^([_%w%.]+)%s+(.*)")
  82         if not name then
  83                 luadoc.logger:warn("parameter `name' not defined [["..text.."]]: skipping")
  84                 return
  85         end
  86         local i = table.foreachi(block[tag], function (i, v)
  87                 if v == name then
  88                         return i
  89                 end
  90         end)
  91         if i == nil then
  92                 luadoc.logger:warn(string.format("documenting undefined parameter `%s'", name))
  93                 table.insert(block[tag], name)
  94         end
  95         block[tag][name] = desc
  96 end
  97
  98 -------------------------------------------------------------------------------
  99
 100 local function release (tag, block, text)
 101         block[tag] = text
 102 end
 103
 104 -------------------------------------------------------------------------------
 105
 106 local function ret (tag, block, text)
 107         tag = "ret"
 108         if type(block[tag]) == "string" then
 109                 block[tag] = { block[tag], text }
 110         elseif type(block[tag]) == "table" then
 111                 table.insert(block[tag], text)
 112         else
 113                 block[tag] = text
 114         end
 115 end
 116
 117 -------------------------------------------------------------------------------
 118 -- @see ret
 119
 120 local function see (tag, block, text)
 121         -- see is always an array
 122         block[tag] = block[tag] or {}
 123
 124         -- remove trailing "."
 125         text = string.gsub(text, "(.*)%.$", "%1")
 126
 127         local s = util.split("%s*,%s*", text)
 128
 129         table.foreachi(s, function (_, v)
 130                 table.insert(block[tag], v)
 131         end)
 132 end
 133
 134 -------------------------------------------------------------------------------
 135 -- @see ret
 136
 137 local function usage (tag, block, text)
 138         if type(block[tag]) == "string" then
 139                 block[tag] = { block[tag], text }
 140         elseif type(block[tag]) == "table" then
 141                 table.insert(block[tag], text)
 142         else
 143                 block[tag] = text
 144         end
 145 end
 146
 147 -------------------------------------------------------------------------------
 148
 149 local handlers = {}
 150 handlers["author"] = author
 151 handlers["class"] = class
 152 handlers["copyright"] = copyright
 153 handlers["description"] = description
 154 handlers["field"] = field
 155 handlers["name"] = name
 156 handlers["param"] = param
 157 handlers["release"] = release
 158 handlers["return"] = ret
 159 handlers["see"] = see
 160 handlers["usage"] = usage
 161
 162 -------------------------------------------------------------------------------
 163
 164 function handle (tag, block, text)
 165         if not handlers[tag] then
 166                 luadoc.logger:error(string.format("undefined handler for tag `%s'", tag))
 167                 return
 168         end
 169 --      assert(handlers[tag], string.format("undefined handler for tag `%s'", tag))
 170         return handlers[tag](tag, block, text)
 171 end