Skip to content

Commit 259c09b

Browse files
XandarosXandaros
committed
Document preprocessor directives
Close GmodStarfall#127
1 parent 7cd04a5 commit 259c09b

6 files changed

Lines changed: 150 additions & 1 deletion

File tree

‎docgen/docletsfhtml.lua‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,18 @@ function hook_link(hookname, doc, from)
115115
return href
116116
end
117117

118+
function directive_link ( dirname, doc, from )
119+
assert( dirname )
120+
assert( doc )
121+
from = from or ""
122+
123+
if doc.directives[ dirname ] == nil then return end
124+
125+
local href = "directives.html"
126+
string.gsub( from, "/", function () href = "../" .. href end )
127+
return href
128+
end
129+
118130
-------------------------------------------------------------------------------
119131
-- Returns the name of the html file to be generated from a lua(doc) file.
120132
-- Files with "lua" or "luadoc" extensions are replaced by "html" extension.
@@ -291,6 +303,14 @@ function start (doc)
291303
include("hooks.lp", {doc=doc, hook_doc=doc})
292304
f:close()
293305

306+
local filename = options.output_dir .. "directives.html"
307+
logger:info( "generating file `%s'", filename )
308+
local f = lfs.open( filename, "w" )
309+
assert( f, string.format( "could not open `%s' for writing", filename ) )
310+
io.output( f )
311+
include( "directives.lp", { doc = doc, dir_doc = doc } )
312+
f:close()
313+
294314
-- copy extra files
295315
local f = lfs.open(options.output_dir.."luadoc.css", "w")
296316
io.output(f)

‎docgen/html/directives.lp‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
2+
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3+
<html>
4+
<head>
5+
<title>Reference</title>
6+
<link rel="stylesheet" href="<?lua= docletsfhtml.link('luadoc.css', 'hooks.html')?>" type="text/css" />
7+
<!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/-->
8+
</head>
9+
10+
<body>
11+
<div id="container">
12+
13+
<div id="product">
14+
<div id="product_logo"></div>
15+
<div id="product_name"><big><b></b></big></div>
16+
<div id="product_description"></div>
17+
</div> <!-- id="product" -->
18+
19+
<div id="main">
20+
21+
<div id="navigation">
22+
<?lua=docletsfhtml.include("menu.lp", { doc=doc, hook_doc=hook_doc })?>
23+
24+
</div><!-- id="navigation" -->
25+
26+
<div id="content">
27+
28+
<h1>Preprocessor directives</h1>
29+
30+
<p>List of preprocessor directives</p>
31+
32+
<h2>List</h2>
33+
<table class="hook_list">
34+
<?lua for _, dir_name in ipairs(dir_doc.directives) do
35+
local dir_data = dir_doc.directives[dir_name]?>
36+
<tr>
37+
<td class="name" nowrap><a href="#<?lua=dir_data.name?>">--@<?lua=dir_name?></a>&nbsp;<?lua=table.concat(dir_data.param, ", ")?></td>
38+
<td class="summary"><?lua=dir_data.summary?></td>
39+
</tr>
40+
<?lua end?>
41+
</table>
42+
43+
<br/>
44+
<br/>
45+
46+
<dl class="hook">
47+
<?lua for _, dir_name in ipairs(dir_doc.directives) do?>
48+
<?lua local dir = dir_doc.directives[dir_name] ?>
49+
<dt><a name="<?lua=dir.name?>"></a><strong>--@<?lua=dir.name?></strong>&nbsp;<?lua=table.concat(dir.param, ", ")?></dt>
50+
<dd>
51+
<?lua=dir.description or ""?>
52+
53+
<?lua if type( dir.param ) == "table" and #dir.param > 0 then?>
54+
<h3>Parameters:</h3>
55+
<ul>
56+
<li>
57+
<code><em><?lua=dir.param[1]?></em></code>: <?lua=dir.param[dir.param[1]] or ""?>
58+
</li>
59+
</ul>
60+
<?lua end?>
61+
62+
<?lua if type(dir.usage) == "string" then?>
63+
<h3>Usage:</h3>
64+
<ul><pre class=example><?lua=dir.usage?></pre></ul>
65+
<?lua elseif type(dir.usage) == "table" then?>
66+
<h3>Usage:</h3>
67+
<ul>
68+
<?lua for _, usage in ipairs(dir.usage) do?>
69+
<li><pre class=example><?lua= usage ?></pre></li>
70+
<?lua end?>
71+
</ul>
72+
<?lua end?>
73+
74+
</dd>
75+
<?lua end?>
76+
</dl>
77+
78+
</div> <!-- id="content" -->
79+
80+
</div> <!-- id="main" -->
81+
82+
<div id="about">
83+
<p><a href="http://validator.w3.org/check?uri=referer"><img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" /></a></p>
84+
</div> <!-- id="about" -->
85+
86+
</div> <!-- id="container" -->
87+
</body>
88+
</html>

‎docgen/html/menu.lp‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ elseif file_doc then
77
from = "files/.."..file_doc.name
88
elseif class_doc then
99
from = "classes/.." .. class_doc.name
10+
elseif dir_doc then
11+
from = "directives/.." .. dir_doc.name
1012
else
1113
from = ""
1214
end
@@ -22,6 +24,19 @@ end
2224
</ul>
2325

2426

27+
<h1>Preprocessor directives</h1>
28+
<ul>
29+
<?lua for _, directive in ipairs(doc.directives) do
30+
if dir_doc and dir_doc.name == directive then?>
31+
<li><strong><?lua=directive?></strong></li>
32+
<?lua else?>
33+
<li>
34+
<a href="<?lua=docletsfhtml.directive_link( directive, doc, from )?>#<?lua=directive?>">--@<?lua=directive?></a>
35+
</li>
36+
<?lua end
37+
end?>
38+
</ul>
39+
2540
<!-- Module list -->
2641
<?lua if not options.nolibs and #doc.libraries > 0 then?>
2742
<h1>Libraries</h1>

‎docgen/tagletsf.lua‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -228,7 +228,7 @@ local function parse_comment ( block, first_line, libs, classes )
228228
currenttag = tag
229229
currenttext = text
230230
else
231-
currenttext = util.concat(currenttext, line)
231+
currenttext = util.concat( currenttext, "\n" .. line )
232232
assert(string.sub(currenttext, 1, 1) ~= " ", string.format("`%s', `%s'", currenttext, line))
233233
end
234234
end)
@@ -440,6 +440,11 @@ function parse_file (filepath, doc)
440440
doc.hooks[t.name] = t
441441
end
442442

443+
for t in class_iterator( blocks, "directive" )() do
444+
table.insert( doc.directives, t.name )
445+
doc.directives[ t.name ] = t
446+
end
447+
443448
local function union ( tbl1, tbl2 )
444449
for k, v in pairs( tbl2 ) do
445450
if type( k ) == "number" then
@@ -536,11 +541,13 @@ function start (files, doc)
536541
files = {},
537542
libraries = {},
538543
hooks = {},
544+
directives = {},
539545
classes = {}
540546
}
541547
assert( doc.files, "undefined `files' field" )
542548
assert( doc.libraries, "undefined `libraries' field" )
543549
assert( doc.hooks, "undefined `hooks' field" )
550+
assert( doc.directives, "undefined `directives' field" )
544551
assert( doc.classes, "undefined `classes' field" )
545552

546553
table.foreachi(files, function (_, path)
@@ -560,6 +567,7 @@ function start (files, doc)
560567
recsort( doc.files )
561568
recsort( doc.libraries )
562569
recsort( doc.hooks )
570+
recsort( doc.directives )
563571
recsort( doc.classes )
564572

565573
return doc

‎docgen/tagletsftags.lua‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ end
3535
local function class (tag, block, text)
3636
block[tag] = text
3737
if text == "hook" then block.param = block.param or {} end
38+
if text == "directive" then block.param = block.param or {} end
3839
if text == "class" then
3940
block.typtbl = check_class( block.code[ 1 ] )
4041
end

‎lua/starfall/preprocessor.lua‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -149,3 +149,20 @@ local function directive_sharedscreen(args, filename, data)
149149

150150
end
151151
SF.Preprocessor.SetGlobalDirective("sharedscreen",directive_sharedscreen)
152+
153+
--- Mark a file to be included in the upload.
154+
-- This is required to use the file in require() and dofile()
155+
-- @name include
156+
-- @class directive
157+
-- @param path Path to the file
158+
159+
--- Set the name of the script.
160+
-- This will become the name of the tab and will show on the overlay of the processor
161+
-- @name name
162+
-- @class directive
163+
-- @param name Name of the script
164+
165+
--- For screens, make the script run on the server, as well.
166+
-- You can use "if SERVER" and "if CLIENT" to determine if the script is currently being run on the server or the client, respectively.
167+
-- @name sharedscreen
168+
-- @class directive

0 commit comments

Comments
 (0)