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