← Back to branch summary

~mudlet-makers/mudlet/gmcp

« back to all changes in this revision

Viewing changes to src/mudlet-lua/lua/luadoc/taglet/standard/tags.lua

  • Committer: Vadim Peretokin
  • Date: 2010-08-28 18:10:10 UTC
  • Revision ID: vadi@vadi-laptop-20100828181010-bew8lo0qqqdxajmu
Added missing files.

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/mudlet-lua/lua/luadoc/taglet/standard/tags.lua
 
1
-- added filename tag
 
2
 
 
3
-------------------------------------------------------------------------------
 
4
-- Handlers for several tags
 
5
-- @release $Id: tags.lua,v 1.8 2007/09/05 12:39:09 tomas Exp $
 
6
-------------------------------------------------------------------------------
 
7
 
 
8
local luadoc = require "luadoc"
 
9
local util = require "luadoc.util"
 
10
local string = require "string"
 
11
local table = require "table"
 
12
local assert, type, tostring = assert, type, tostring
 
13
 
 
14
module "luadoc.taglet.standard.tags"
 
15
 
 
16
-------------------------------------------------------------------------------
 
17
 
 
18
local function author (tag, block, text)
 
19
        block[tag] = block[tag] or {}
 
20
        if not text then
 
21
                luadoc.logger:warn("author `name' not defined [["..text.."]]: skipping")
 
22
                return
 
23
        end
 
24
        table.insert (block[tag], text)
 
25
end
 
26
 
 
27
-------------------------------------------------------------------------------
 
28
-- Set the class of a comment block. Classes can be "module", "function", 
 
29
-- "table". The first two classes are automatic, extracted from the source code
 
30
 
 
31
local function class (tag, block, text)
 
32
        block[tag] = text
 
33
end
 
34
 
 
35
-------------------------------------------------------------------------------
 
36
 
 
37
local function copyright (tag, block, text)
 
38
        block[tag] = text
 
39
end
 
40
 
 
41
-------------------------------------------------------------------------------
 
42
 
 
43
local function description (tag, block, text)
 
44
        block[tag] = text
 
45
end
 
46
 
 
47
-------------------------------------------------------------------------------
 
48
 
 
49
local function filename (tag, block, text)
 
50
        block[tag] = text
 
51
end
 
52
 
 
53
-------------------------------------------------------------------------------
 
54
 
 
55
local function field (tag, block, text)
 
56
        if block["class"] ~= "table" then
 
57
                luadoc.logger:warn("documenting `field' for block that is not a `table'")
 
58
        end
 
59
        block[tag] = block[tag] or {}
 
60
 
 
61
        local _, _, name, desc = string.find(text, "^([_%w%.]+)%s+(.*)")
 
62
        assert(name, "field name not defined")
 
63
        
 
64
        table.insert(block[tag], name)
 
65
        block[tag][name] = desc
 
66
end
 
67
 
 
68
-------------------------------------------------------------------------------
 
69
-- Set the name of the comment block. If the block already has a name, issue
 
70
-- an error and do not change the previous value
 
71
 
 
72
local function name (tag, block, text)
 
73
        if block[tag] and block[tag] ~= text then
 
74
                luadoc.logger:error(string.format("block name conflict: `%s' -> `%s'", block[tag], text))
 
75
        end
 
76
        
 
77
        block[tag] = text
 
78
end
 
79
 
 
80
-------------------------------------------------------------------------------
 
81
-- Processes a parameter documentation.
 
82
-- @param tag String with the name of the tag (it must be "param" always).
 
83
-- @param block Table with previous information about the block.
 
84
-- @param text String with the current line beeing processed.
 
85
 
 
86
local function param (tag, block, text)
 
87
        block[tag] = block[tag] or {}
 
88
        -- TODO: make this pattern more flexible, accepting empty descriptions
 
89
        local _, _, name, desc = string.find(text, "^([_%w%.]+)%s+(.*)")
 
90
        if not name then
 
91
                luadoc.logger:warn("parameter `name' not defined [["..text.."]]: skipping")
 
92
                return
 
93
        end
 
94
        local i = table.foreachi(block[tag], function (i, v)
 
95
                if v == name then
 
96
                        return i
 
97
                end
 
98
        end)
 
99
        if i == nil then
 
100
                luadoc.logger:warn(string.format("documenting undefined parameter `%s'", name))
 
101
                table.insert(block[tag], name)
 
102
        end
 
103
        block[tag][name] = desc
 
104
end
 
105
 
 
106
-------------------------------------------------------------------------------
 
107
 
 
108
local function release (tag, block, text)
 
109
        block[tag] = text
 
110
end
 
111
 
 
112
-------------------------------------------------------------------------------
 
113
 
 
114
local function ret (tag, block, text)
 
115
        tag = "ret"
 
116
        if type(block[tag]) == "string" then
 
117
                block[tag] = { block[tag], text }
 
118
        elseif type(block[tag]) == "table" then
 
119
                table.insert(block[tag], text)
 
120
        else
 
121
                block[tag] = text
 
122
        end
 
123
end
 
124
 
 
125
-------------------------------------------------------------------------------
 
126
-- @see ret
 
127
 
 
128
local function see (tag, block, text)
 
129
        -- see is always an array
 
130
        block[tag] = block[tag] or {}
 
131
        
 
132
        -- remove trailing "."
 
133
        text = string.gsub(text, "(.*)%.$", "%1")
 
134
        
 
135
        local s = util.split("%s*,%s*", text)                   
 
136
        
 
137
        table.foreachi(s, function (_, v)
 
138
                table.insert(block[tag], v)
 
139
        end)
 
140
end
 
141
 
 
142
-------------------------------------------------------------------------------
 
143
-- @see ret
 
144
 
 
145
local function usage (tag, block, text)
 
146
        if type(block[tag]) == "string" then
 
147
                block[tag] = { block[tag], text }
 
148
        elseif type(block[tag]) == "table" then
 
149
                table.insert(block[tag], text)
 
150
        else
 
151
                block[tag] = text
 
152
        end
 
153
end
 
154
 
 
155
-------------------------------------------------------------------------------
 
156
 
 
157
local handlers = {}
 
158
handlers["author"] = author
 
159
handlers["class"] = class
 
160
handlers["copyright"] = copyright
 
161
handlers["description"] = description
 
162
handlers["field"] = field
 
163
handlers["name"] = name
 
164
handlers["param"] = param
 
165
handlers["release"] = release
 
166
handlers["return"] = ret
 
167
handlers["see"] = see
 
168
handlers["usage"] = usage
 
169
handlers["filename"] = filename
 
170
 
 
171
-------------------------------------------------------------------------------
 
172
 
 
173
function handle (tag, block, text)
 
174
        if not handlers[tag] then
 
175
                luadoc.logger:error(string.format("undefined handler for tag `%s'", tag))
 
176
                return
 
177
        end
 
178
--      assert(handlers[tag], string.format("undefined handler for tag `%s'", tag))
 
179
        return handlers[tag](tag, block, text)
 
180
end