+ LDoc

65 files changed, 2464 insertions, 0 deletions

diff --git a/Data/Libraries/LDoc/tests/annot/annot.lua b/Data/Libraries/LDoc/tests/annot/annot.lua
new file mode 100644
index 0000000..7ebc278
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/annot/annot.lua
@@ -0,0 +1,21 @@
+----------------
+-- Testing annotations
+-- @module annot
+
+--- first fun.
+function first()
+   if boo then
+      local bar = do_something()
+      if bar then
+      ---  @fixme otherwise do what?
+      end
+   end
+end
+
+--- second try.
+function second()
+   --- @todo also handle foo case
+   if bar then
+
+   end
+end
diff --git a/Data/Libraries/LDoc/tests/bad.lua b/Data/Libraries/LDoc/tests/bad.lua
new file mode 100644
index 0000000..70df107
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/bad.lua
@@ -0,0 +1,13 @@
+-------
+-- @module bad
+
+local bad = {}
+
+--------
+-- inference fails! Have to explicitly
+-- declare the function and its arguments
+bad['entry'] = function(one)
+end
+
+return bad
+
diff --git a/Data/Libraries/LDoc/tests/classes.lua b/Data/Libraries/LDoc/tests/classes.lua
new file mode 100644
index 0000000..6248b23
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/classes.lua
@@ -0,0 +1,25 @@
+----------------------
+-- a module containing some classes.
+-- @module classes
+
+local _M = {}
+
+---- a useful class.
+-- @type Bonzo
+
+_M.Bonzo = class()
+
+--- a method.
+-- function one; reference to @{one.md.classes|documentation}
+function Bonzo:one()
+
+end
+
+--- a metamethod
+-- function __tostring
+function Bonzo:__tostring()
+
+end
+
+return M
+
diff --git a/Data/Libraries/LDoc/tests/complex/lua/complex/convert/basic.lua b/Data/Libraries/LDoc/tests/complex/lua/complex/convert/basic.lua
new file mode 100644
index 0000000..b11572c
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/complex/lua/complex/convert/basic.lua
@@ -0,0 +1,6 @@
+--- oh.
+
+--- convert.
+function M.convert ()
+
+end
diff --git a/Data/Libraries/LDoc/tests/complex/lua/complex/display.lua b/Data/Libraries/LDoc/tests/complex/lua/complex/display.lua
new file mode 100644
index 0000000..c184775
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/complex/lua/complex/display.lua
@@ -0,0 +1,10 @@
+--- dee.
+
+--- display this.
+function M.display_this()
+end
+
+--- display that.
+-- @see display_this
+function M.display_that()
+end
diff --git a/Data/Libraries/LDoc/tests/complex/lua/complex/init.lua b/Data/Libraries/LDoc/tests/complex/lua/complex/init.lua
new file mode 100644
index 0000000..25b2393
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/complex/lua/complex/init.lua
@@ -0,0 +1,12 @@
+--- doo
+
+--- start.
+function M.start()
+end
+
+--- run.
+-- @see complex.display.display_this
+function M.run()
+end
+
+
diff --git a/Data/Libraries/LDoc/tests/complex/lua/complex/util/init.lua b/Data/Libraries/LDoc/tests/complex/lua/complex/util/init.lua
new file mode 100644
index 0000000..1d068d3
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/complex/lua/complex/util/init.lua
@@ -0,0 +1,7 @@
+--- wo.
+
+--- open.
+-- @see convert.basic
+function M.open ()
+
+end
diff --git a/Data/Libraries/LDoc/tests/complex/lua/complex/util/parse.lua b/Data/Libraries/LDoc/tests/complex/lua/complex/util/parse.lua
new file mode 100644
index 0000000..6078c47
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/complex/lua/complex/util/parse.lua
@@ -0,0 +1,7 @@
+--- wee
+
+--- parse.
+-- @see util.open
+function M.parse ()
+
+end
diff --git a/Data/Libraries/LDoc/tests/config.ld b/Data/Libraries/LDoc/tests/config.ld
new file mode 100644
index 0000000..4c9cbae
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/config.ld
@@ -0,0 +1,5 @@
+format='markdown'
+project = 'Basic Example'
+file = {'types.lua','classes.lua'}
+use_markdown_titles=true
+topics = {'one.md','two.md'}
diff --git a/Data/Libraries/LDoc/tests/easy/easy.lua b/Data/Libraries/LDoc/tests/easy/easy.lua
new file mode 100644
index 0000000..00dca97
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/easy/easy.lua
@@ -0,0 +1,8 @@
+--- simplified LDoc colon style.
+-- You have to use -C flag or 'colon=true' for this one!
+module 'easy'
+
+--- First one.
+-- string: name
+-- int: age
+function first(name,age) end
diff --git a/Data/Libraries/LDoc/tests/example/config.ld b/Data/Libraries/LDoc/tests/example/config.ld
new file mode 100644
index 0000000..f0d8a38
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/example/config.ld
@@ -0,0 +1,14 @@
+-- ldoc configuration file
+title = "testmod docs"
+project = "testmod"
+
+description = [[
+This description applies to the project as a whole.
+]]
+
+alias("p","param")
+
+file = {'mod1.lua','modtest.lua','mylib.c'}
+
+new_type("macro","Macros")
+
diff --git a/Data/Libraries/LDoc/tests/example/laurent/config.ld b/Data/Libraries/LDoc/tests/example/laurent/config.ld
new file mode 100644
index 0000000..5f4b8ae
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/example/laurent/config.ld
@@ -0,0 +1,3 @@
+style = true
+template = true
+file = 'mod1.lua'
diff --git a/Data/Libraries/LDoc/tests/example/laurent/ldoc.css b/Data/Libraries/LDoc/tests/example/laurent/ldoc.css
new file mode 100644
index 0000000..7c9023d
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/example/laurent/ldoc.css
@@ -0,0 +1,271 @@
+/* BEGIN RESET
+
+Copyright (c) 2010, Yahoo! Inc. All rights reserved.
+Code licensed under the BSD License:
+http://developer.yahoo.com/yui/license.html
+version: 2.8.2r1
+*/
+html {
+    color: #000;
+    background: #FFF;
+}
+body,div,dl,dt,dd,ul,ol,li,h1,h2,h3,h4,h5,h6,pre,code,form,fieldset,legend,input,button,textarea,p,blockquote,th,td {
+    margin: 0;
+    padding: 0;
+}
+table {
+    border-collapse: collapse;
+    border-spacing: 0;
+}
+fieldset,img {
+    border: 0;
+}
+address,caption,cite,code,dfn,em,strong,th,var,optgroup {
+    font-style: inherit;
+    font-weight: inherit;
+}
+del,ins {
+    text-decoration: none;
+}
+li {
+    list-style: bullet;
+    margin-left: 20px;
+}
+caption,th {
+    text-align: left;
+}
+h1,h2,h3,h4,h5,h6 {
+    font-size: 100%;
+    font-weight: bold;
+}
+q:before,q:after {
+    content: '';
+}
+abbr,acronym {
+    border: 0;
+    font-variant: normal;
+}
+sup {
+    vertical-align: baseline;
+}
+sub {
+    vertical-align: baseline;
+}
+legend {
+    color: #000;
+}
+input,button,textarea,select,optgroup,option {
+    font-family: inherit;
+    font-size: inherit;
+    font-style: inherit;
+    font-weight: inherit;
+}
+input,button,textarea,select {*font-size:100%;
+}
+/* END RESET */
+
+body {
+    margin-left: 1em;
+    margin-right: 1em;
+    font-family: arial, helvetica, geneva, sans-serif;
+    background-color: #ffffff; margin: 0px;
+}
+
+code, tt { font-family: monospace; }
+
+body, p, td, th { font-size: .95em; line-height: 1.2em;}
+
+p, ul { margin: 10px 0 0 10px;}
+
+strong { font-weight: bold;}
+
+em { font-style: italic;}
+
+h1 {
+    font-size: 1.5em;
+    margin: 0 0 20px 0;
+}
+h2, h3, h4 { margin: 15px 0 10px 0; }
+h2 { font-size: 1.25em; }
+h3 { font-size: 1.15em; }
+h4 { font-size: 1.06em; }
+
+a:link { font-weight: bold; color: #004080; text-decoration: none; }
+a:visited { font-weight: bold; color: #006699; text-decoration: none; }
+a:link:hover { text-decoration: underline; }
+
+hr {
+    color:#cccccc;
+    background: #00007f;
+    height: 1px;
+}
+
+blockquote { margin-left: 3em; }
+
+ul { list-style-type: disc; }
+
+p.name {
+    font-family: "Andale Mono", monospace;
+    padding-top: 1em;
+}
+
+pre.example {
+    background-color: rgb(245, 245, 245);
+    border: 1px solid silver;
+    padding: 10px;
+    margin: 10px 0 10px 0;
+    font-family: "Andale Mono", monospace;
+    font-size: .85em;
+}
+
+pre {
+    background-color: rgb(245, 245, 245);
+    border: 1px solid silver;
+    padding: 10px;
+    margin: 10px 0 10px 0;
+    font-family: "Andale Mono", monospace;
+}
+
+
+table.index { border: 1px #00007f; }
+table.index td { text-align: left; vertical-align: top; }
+
+#container {
+    margin-left: 1em;
+    margin-right: 1em;
+    background-color: #f0f0f0;
+}
+
+#product {
+    text-align: center;
+    border-bottom: 1px solid #cccccc;
+    background-color: #ffffff;
+}
+
+#product big {
+    font-size: 2em;
+}
+
+#main {
+    background-color: #f0f0f0;
+    border-left: 2px solid #cccccc;
+}
+
+#navigation {
+    float: left;
+    width: 18em;
+    vertical-align: top;
+    background-color: #f0f0f0;
+    overflow: visible;
+    position: fixed;
+}
+
+#navigation h2 {
+    background-color:#e7e7e7;
+    font-size:1.1em;
+    color:#000000;
+    text-align: left;
+    padding:0.2em;
+    border-top:1px solid #dddddd;
+    border-bottom:1px solid #dddddd;
+}
+
+#navigation ul
+{
+    font-size:1em;
+    list-style-type: none;
+    margin: 1px 1px 10px 1px;
+}
+
+#navigation li {
+    text-indent: -1em;
+    display: block;
+    margin: 3px 0px 0px 22px;
+}
+
+#navigation li li a {
+    margin: 0px 3px 0px -1em;
+}
+
+#content {
+    margin-left: 18em;
+    padding: 1em;
+    border-left: 2px solid #cccccc;
+    border-right: 2px solid #cccccc;
+    background-color: #ffffff;
+}
+
+#about {
+    clear: both;
+    padding: 5px;
+    border-top: 2px solid #cccccc;
+    background-color: #ffffff;
+}
+
+@media print {
+    body {
+        font: 12pt "Times New Roman", "TimeNR", Times, serif;
+    }
+    a { font-weight: bold; color: #004080; text-decoration: underline; }
+
+    #main {
+        background-color: #ffffff;
+        border-left: 0px;
+    }
+
+    #container {
+        margin-left: 2%;
+        margin-right: 2%;
+        background-color: #ffffff;
+    }
+
+    #content {
+        padding: 1em;
+        background-color: #ffffff;
+    }
+
+    #navigation {
+        display: none;
+    }
+    pre.example {
+        font-family: "Andale Mono", monospace;
+        font-size: 10pt;
+        page-break-inside: avoid;
+    }
+}
+
+table.module_list {
+    border-width: 1px;
+    border-style: solid;
+    border-color: #cccccc;
+    border-collapse: collapse;
+}
+table.module_list td {
+    border-width: 1px;
+    padding: 3px;
+    border-style: solid;
+    border-color: #cccccc;
+}
+table.module_list td.name { background-color: #f0f0f0; }
+table.module_list td.summary { width: 100%; }
+
+
+table.function_list {
+    border-width: 1px;
+    border-style: solid;
+    border-color: #cccccc;
+    border-collapse: collapse;
+}
+table.function_list td {
+    border-width: 1px;
+    padding: 3px;
+    border-style: solid;
+    border-color: #cccccc;
+}
+table.function_list td.name { background-color: #f0f0f0; }
+table.function_list td.summary { width: 100%; }
+
+dl.table dt, dl.function dt {border-top: 1px solid #ccc; padding-top: 1em;}
+dl.table dd, dl.function dd {padding-bottom: 1em; margin: 10px 0 0 20px;}
+dl.table h3, dl.function h3 {font-size: .95em;}
+
diff --git a/Data/Libraries/LDoc/tests/example/laurent/ldoc.ltp b/Data/Libraries/LDoc/tests/example/laurent/ldoc.ltp
new file mode 100644
index 0000000..7e4341b
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/example/laurent/ldoc.ltp
@@ -0,0 +1,201 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
+<head>
+    <title>$(ldoc.title)</title>
+    <link rel="stylesheet" href="$(ldoc.css)" type="text/css" />
+</head>
+<body>
+
+<div id="container">
+
+<div id="product">
+	<div id="product_logo"></div>
+	<div id="product_name"><big><b></b></big></div>
+	<div id="product_description"></div>
+</div> <!-- id="product" -->
+
+
+<div id="main">
+
+# local no_spaces = ldoc.no_spaces
+# local use_li = ldoc.use_li
+# local display_name = ldoc.display_name
+# local iter = ldoc.modules.iter
+# local M = ldoc.markup
+
+<!-- Menu -->
+
+<div id="navigation">
+
+<h1>$(ldoc.project)</h1>
+
+# if not ldoc.single and module then -- reference back to project index
+<ul>
+  <li><a href="../$(ldoc.output).html">Index</a></li>
+</ul>
+# else
+<p>$(ldoc.description)</p>
+# end
+
+
+
+# -------- contents of project ----------
+# if not ldoc.no_summary then
+# local this_mod = module and module.name
+# for kind, mods, type in ldoc.kinds() do
+#  if not ldoc.kinds_allowed or ldoc.kinds_allowed[type] then
+<h2>$(kind)</h2>
+<ul>
+#  for mod in mods() do
+#   if mod.name == this_mod then -- highlight current module, link to others
+  <li><strong>$(mod.name)</strong></li>
+#   else
+  <li><a href="$(ldoc.ref_to_module(mod))">$(mod.name)</a></li>
+#   end
+#  end
+# end
+#end
+</ul>
+# else
+<ul>
+# for kind, items in module.kinds() do
+<h2>$(kind)</h2>
+# for item in items() do
+    <li><a href="#$(item.name)">$(display_name(item))</a></li>
+# end end
+</ul>
+#end
+
+# --------- contents of module -------------
+# if module and not ldoc.no_summary and #module.items > 0 then
+<h2>Contents</h2>
+<ul>
+# for kind,items in module.kinds() do
+<li><a href="#$(no_spaces(kind))">$(kind)</a></li>
+# end
+</ul>
+# end
+
+</div>
+
+<div id="content">
+
+#if module then
+<h1>$(ldoc.titlecase(module.type)) <code>$(module.name)</code></h1>
+# end
+
+# if ldoc.body then -- verbatim HTML as contents; 'non-code' entries
+    $(ldoc.body)
+# elseif module then -- module documentation
+#   ldoc.item = module  -- context for M()
+<p>$(M(module.summary))</p>
+<p>$(M(module.description))</p>
+
+# if not ldoc.no_summary then
+# -- bang out the tables of item types for this module (e.g Functions, Tables, etc)
+# for kind,items in module.kinds() do
+<h2><a href="#$(no_spaces(kind))">$(kind)</a></h2>
+<table class="function_list">
+#  for item in items() do
+	<tr>
+	<td class="name" nowrap><a href="#$(item.name)">$(display_name(item))</a></td>
+	<td class="summary">$(M(item.summary))</td>
+	</tr>
+#  end -- for items
+</table>
+#end -- for kinds
+
+<br/>
+<br/>
+
+#end -- if not no_summary
+
+# --- currently works for both Functions and Tables. The params field either contains
+# --- function parameters or table fields.
+# local show_return = not ldoc.no_return_or_parms
+# local show_parms = show_return
+# for kind, items in module.kinds() do
+    <h2><a name="$(no_spaces(kind))"></a>$(kind)</h2>
+    $(M(module.kinds:get_section_description(kind)))
+    <dl class="function">
+#  for item in items() do ldoc.item = item -- provides context for M()
+    <dt>
+    <a name = "$(item.name)"></a>
+    <strong>$(display_name(item))</strong>
+    </dt>
+    <dd>
+    $(M(item.summary..' <br />'..(item.description or '')))
+
+#  if show_parms and item.params and #item.params > 0 then
+    <h3>$(module.kinds:type_of(item).subnames):</h3>
+    <ul>
+#   for p in iter(item.params) do
+       <li><code><em>$(p)</em></code>: $(M(item.params[p]))</li>
+#   end -- for
+    </ul>
+#   end -- if params
+
+#   if show_return and item.ret then
+#     local li,il = use_li(item.ret)
+    <h3>Returns:</h3>
+    <ol>
+#     for r in iter(item.ret) do
+        $(li)$(M(r))$(il)
+#     end -- for
+    </ol>
+#   end -- if returns
+
+#   if item.usage then
+#     local li,il = use_li(item.usage)
+    <h3>Usage:</h3>
+    <ul>
+#     for usage in iter(item.usage) do
+        $(li)<pre class="example">$(usage)</pre>$(il)
+#     end -- for
+    </ul>
+#   end -- if usage
+
+#   if item.see then
+#     local li,il = use_li(item.see)
+    <h3>see also:</h3>
+    <ul>
+#     for see in iter(item.see) do
+         $(li)<a href="$(ldoc.href(see))">$(see.label)</a>$(il)
+#    end -- for
+    </ul>
+#   end -- if see
+</dd>
+# end -- for items
+</dl>
+# end -- for kinds
+
+# else -- if module; project-level contents
+
+# if ldoc.description then
+  <p>$(M(ldoc.description))</p>
+# end
+
+# for kind, mods in ldoc.kinds() do
+<h2>$(kind)</h2>
+# kind = kind:lower()
+<table class="module_list">
+# for m in mods() do
+	<tr>
+		<td class="name" nowrap><a href="$(no_spaces(kind))/$(m.name).html">$(m.name)</a></td>
+		<td class="summary">$(M(m.summary))</td>
+	</tr>
+#  end -- for modules
+</table>
+# end -- for kinds
+# end -- if module
+
+</div> <!-- id="content" -->
+</div> <!-- id="main" -->
+<div id="about">
+<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc</a></i>
+</div> <!-- id="about" -->
+</div> <!-- id="container" -->
+</body>
+</html>
\ No newline at end of file
diff --git a/Data/Libraries/LDoc/tests/example/laurent/mod1.lua b/Data/Libraries/LDoc/tests/example/laurent/mod1.lua
new file mode 100644
index 0000000..4b5c9b0
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/example/laurent/mod1.lua
@@ -0,0 +1,61 @@
+---------------------------
+-- Test module providing bonzo.dog.
+-- Rest is a longer description
+-- @class module
+-- @name mod1
+
+--- zero function. Two new ldoc features here; item types
+-- can be used directly as tags, and aliases for tags
+-- can be defined in config.lp.
+-- @function zero_fun
+-- @param k1 first
+-- @param k2 second
+
+--- first function. Some description
+-- @param p1 first parameter
+-- @param[opt] p2 second parameter
+-- @param[optchain] p3 third parameter
+function mod1.first_fun(p1,p2,p3)
+end
+
+-------------------------
+-- second function.
+-- @param ... var args!
+function mod1.second_function(...)
+end
+
+------------
+-- third function. Can also provide parameter comments inline,
+-- provided they follow this pattern.
+function mod1.third_function(
+    alpha, -- correction A
+    beta, -- correction B
+    gamma -- factor C
+    )
+end
+
+-----
+-- A useful macro. This is an example of a custom 'kind'.
+-- @macro first_macro
+-- @see second_function
+
+---- general configuration table
+-- @table config
+-- @field A alpha
+-- @field B beta
+-- @field C gamma
+mod1.config = {
+    A = 1,
+    B = 2,
+    C = 3
+}
+
+--[[--
+Another function. Using a Lua block comment
+@param p a parameter
+]]
+function mod1.zero_function(p)
+end
+
+
+
diff --git a/Data/Libraries/LDoc/tests/example/mod1.lua b/Data/Libraries/LDoc/tests/example/mod1.lua
new file mode 100644
index 0000000..5475818
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/example/mod1.lua
@@ -0,0 +1,81 @@
+---------------------------
+-- Test module providing bonzo.dog.
+-- Rest is a longer description
+-- @class module
+-- @name mod1
+
+--- zero function. Two new ldoc features here; item types
+-- can be used directly as tags, and aliases for tags
+-- can be defined in config.lp.
+-- @function zero_fun
+-- @p k1 first
+-- @p k2 second
+
+--- first function. Some description
+-- @param p1 first parameter
+-- @param p2 second parameter
+function mod1.first_fun(p1,p2)
+end
+
+-------------------------
+-- second function.
+-- @param ... var args!
+function mod1.second_function(...)
+end
+
+------------
+-- third function. Can also provide parameter comments inline,
+-- provided they follow this pattern.
+function mod1.third_function(
+    alpha, -- correction A
+    beta, -- correction B
+    gamma -- factor C
+    )
+end
+
+-----
+-- A useful macro. This is an example of a custom 'kind'.
+-- @macro first_macro
+-- @see second_function
+
+---- general configuration table
+-- @table config
+-- @field A alpha
+-- @field B beta
+-- @field C gamma
+mod1.config = {
+    A = 1,
+    B = 2,
+    C = 3
+}
+
+--[[--
+Another function. Using a Lua block comment
+@param p a parameter
+]]
+function mod1.zero_function(p)
+end
+
+
+-------
+-- Multiple params may match a varargs function.
+-- Generally, ldoc tries to be strict about matching params and formal arguments,
+-- but this is relaxed for varargs: `function other(p,...)`
+-- @param p
+-- @param q
+-- @param r
+function mod1.other(p,...)
+-- something cunning with select(2,...)
+end
+
+-------
+-- A function with typed arguments.
+-- The tparam tag is followed by the 'type'. There is no standard way
+-- to represent Lua types, but you can adopt a convention. Type names
+-- will be resolved. treturn must include a description after the type.
+-- @tparam string name
+-- @tparam number age
+-- @treturn string modified age
+function mod1.typed(name,age)
+
+end
diff --git a/Data/Libraries/LDoc/tests/example/modtest.lua b/Data/Libraries/LDoc/tests/example/modtest.lua
new file mode 100644
index 0000000..cefabf1
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/example/modtest.lua
@@ -0,0 +1,18 @@
+-------
+-- A script.
+-- Scripts are not containers in the sense that modules are,
+-- (although perhaps the idea of 'commands' could be adopted for some utilities)
+-- It allows any upfront script comments to be included in the
+-- documentation. Any long string marked with the 'usage' tag will also appear
+-- in this area.
+--
+-- @script modtest
+
+--- @usage
+local usage = [[
+modtest NAME
+where NAME is your favourite name!
+
+]]
+
+print ('hello',arg[1])
diff --git a/Data/Libraries/LDoc/tests/example/mylib.c b/Data/Libraries/LDoc/tests/example/mylib.c
new file mode 100644
index 0000000..fd9c675
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/example/mylib.c
@@ -0,0 +1,62 @@
+/// A sample C extension.
+// Demonstrates using ldoc's C/C++ support. Can either use /// or /*** */ etc.
+// @module mylib
+#include <string.h>
+#include <math.h>
+
+// includes for Lua
+#include <lua.h>
+#include <lauxlib.h>
+#include <lualib.h>
+
+/***
+Create a table with given array and hash slots.
+@function createtable
+@param narr initial array slots, default 0
+@param nrec initial hash slots, default 0
+*/
+static int l_createtable (lua_State *L) {
+  int narr = luaL_optint(L,1,0);
+  int nrec = luaL_optint(L,2,0);
+  lua_createtable(L,narr,nrec);
+  return 1;
+}
+
+/***
+Solve a quadratic equation.
+@function solve
+@tparam num a coefficient of x^2
+@tparam num b coefficient of x
+@tparam num c constant
+@treturn num first root
+@treturn num second root
+*/
+static int l_solve (lua_State *L) {
+    double a = lua_tonumber(L,1);  // coeff of x*x
+    double b = lua_tonumber(L,2);  // coef of x
+    double c = lua_tonumber(L,3);  // constant
+    double abc = b*b - 4*a*c;
+    if (abc < 0.0) {
+        lua_pushnil(L);
+        lua_pushstring(L,"imaginary roots!");
+        return 2;
+    } else {
+        abc = sqrt(abc);
+        a = 2*a;
+        lua_pushnumber(L,(-b + abc)/a);
+        lua_pushnumber(L,(+b - abc)/a);
+        return 2;
+    }
+}
+
+static const luaL_reg mylib[] = {
+    {"createtable",l_createtable},
+    {"solve",l_solve},
+    {NULL,NULL}
+};
+
+int luaopen_mylib(lua_State *L)
+{
+    luaL_register (L, "mylib", mylib);
+    return 1;
+}
diff --git a/Data/Libraries/LDoc/tests/example/style/config.ld b/Data/Libraries/LDoc/tests/example/style/config.ld
new file mode 100644
index 0000000..6a96275
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/example/style/config.ld
@@ -0,0 +1,14 @@
+file = 'simple.lua'
+project = 'simple'
+description = [[
+a simple project
+
+##References
+
+ - [Background]()
+ - [Discussion]()
+
+]]
+style = true
+template = true
+format = 'markdown'
diff --git a/Data/Libraries/LDoc/tests/example/style/ldoc.css b/Data/Libraries/LDoc/tests/example/style/ldoc.css
new file mode 100644
index 0000000..3b270a1
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/example/style/ldoc.css
@@ -0,0 +1,299 @@
+/* BEGIN RESET
+
+Copyright (c) 2010, Yahoo! Inc. All rights reserved.
+Code licensed under the BSD License:
+http://developer.yahoo.com/yui/license.html
+version: 2.8.2r1
+*/
+html {
+    color: #000;
+    background: #FFF;
+}
+body,div,dl,dt,dd,ul,ol,li,h1,h2,h3,h4,h5,h6,pre,code,form,fieldset,legend,input,button,textarea,p,blockquote,th,td {
+    margin: 0;
+    padding: 0;
+}
+table {
+    border-collapse: collapse;
+    border-spacing: 0;
+}
+fieldset,img {
+    border: 0;
+}
+address,caption,cite,code,dfn,em,strong,th,var,optgroup {
+    font-style: inherit;
+    font-weight: inherit;
+}
+del,ins {
+    text-decoration: none;
+}
+li {
+    list-style: bullet;
+    margin-left: 20px;
+}
+caption,th {
+    text-align: left;
+}
+h1,h2,h3,h4,h5,h6 {
+    font-size: 100%;
+    font-weight: bold;
+}
+q:before,q:after {
+    content: '';
+}
+abbr,acronym {
+    border: 0;
+    font-variant: normal;
+}
+sup {
+    vertical-align: baseline;
+}
+sub {
+    vertical-align: baseline;
+}
+legend {
+    color: #000;
+}
+input,button,textarea,select,optgroup,option {
+    font-family: inherit;
+    font-size: inherit;
+    font-style: inherit;
+    font-weight: inherit;
+}
+input,button,textarea,select {*font-size:100%;
+}
+/* END RESET */
+
+body {
+    margin-left: 1em;
+    margin-right: 1em;
+    font-family: arial, helvetica, geneva, sans-serif;
+    background-color: #ffffff; margin: 0px;
+}
+
+code, tt { font-family: monospace; }
+
+body, p, td, th { font-size: .95em; line-height: 1.2em;}
+
+p, ul { margin: 10px 0 0 10px;}
+
+strong { font-weight: bold;}
+
+em { font-style: italic;}
+
+h1 {
+    font-size: 1.5em;
+    margin: 0 0 20px 0;
+}
+h2, h3, h4 { margin: 15px 0 10px 0; }
+h2 { font-size: 1.25em; }
+h3 { font-size: 1.15em; }
+h4 { font-size: 1.06em; }
+
+a:link { font-weight: bold; color: #004080; text-decoration: none; }
+a:visited { font-weight: bold; color: #006699; text-decoration: none; }
+a:link:hover { text-decoration: underline; }
+
+hr {
+    color:#cccccc;
+    background: #00007f;
+    height: 1px;
+}
+
+blockquote { margin-left: 3em; }
+
+ul { list-style-type: disc; }
+
+p.name {
+    font-family: "Andale Mono", monospace;
+    padding-top: 1em;
+}
+
+pre.example {
+    background-color: rgb(245, 245, 245);
+    border: 1px solid silver;
+    padding: 10px;
+    margin: 10px 0 10px 0;
+    font-family: "Andale Mono", monospace;
+    font-size: .85em;
+}
+
+pre {
+    background-color: rgb(245, 245, 245);
+    border: 1px solid silver;
+    padding: 10px;
+    margin: 10px 0 10px 0;
+    font-family: "Andale Mono", monospace;
+}
+
+
+table.index { border: 1px #00007f; }
+table.index td { text-align: left; vertical-align: top; }
+
+#container {
+    margin-left: 1em;
+    margin-right: 1em;
+    background-color: #f0f0f0;
+}
+
+#product {
+    text-align: center;
+    border-bottom: 1px solid #cccccc;
+    background-color: #ffffff;
+}
+
+#product big {
+    font-size: 2em;
+}
+
+#main {
+    background-color: #f0f0ff;
+    border-left: 2px solid #cccccc;
+}
+
+#navigation {
+    float: left;
+    width: 14em;
+    vertical-align: top;
+    background-color: #f0f0f0;
+    overflow: visible;
+}
+
+#navigation h2 {
+    background-color:#e7e7e7;
+    font-size:1.1em;
+    color:#000000;
+    text-align: left;
+    padding:0.2em;
+    border-top:1px solid #dddddd;
+    border-bottom:1px solid #dddddd;
+}
+
+#navigation ul
+{
+    font-size:1em;
+    list-style-type: none;
+    margin: 1px 1px 10px 1px;
+}
+
+#navigation li {
+    text-indent: -1em;
+    display: block;
+    margin: 3px 0px 0px 22px;
+}
+
+#navigation li li a {
+    margin: 0px 3px 0px -1em;
+}
+
+#content {
+    margin-left: 14em;
+    width: 40em;
+    padding: 1em;
+    border-left: 2px solid #cccccc;
+    border-right: 2px solid #cccccc;
+    background-color: #f0ffff;
+}
+
+#about {
+    clear: both;
+    padding: 5px;
+    border-top: 2px solid #cccccc;
+    background-color: #ffffff;
+}
+
+@media print {
+    body {
+        font: 12pt "Times New Roman", "TimeNR", Times, serif;
+    }
+    a { font-weight: bold; color: #004080; text-decoration: underline; }
+
+    #main {
+        background-color: #ffffff;
+        border-left: 0px;
+    }
+
+    #container {
+        margin-left: 2%;
+        margin-right: 2%;
+        background-color: #ffffff;
+    }
+
+    #content {
+        padding: 1em;
+        background-color: #ffffff;
+    }
+
+    #navigation {
+        display: none;
+    }
+    pre.example {
+        font-family: "Andale Mono", monospace;
+        font-size: 10pt;
+        page-break-inside: avoid;
+    }
+}
+
+table.module_list td {
+    border-width: 1px;
+    padding: 3px;
+    border-style: solid;
+    border-color: #cccccc;
+}
+table.module_list td.name { background-color: #f0f0f0; }
+table.module_list td.summary { width: 100%; }
+
+table.file_list {
+    border-width: 1px;
+    border-style: solid;
+    border-color: #cccccc;
+    border-collapse: collapse;
+}
+table.file_list td {
+    border-width: 1px;
+    padding: 3px;
+    border-style: solid;
+    border-color: #cccccc;
+}
+
+table.file_list td.name { background-color: #fff0ff; }
+
+table.file_list td.summary { width: 100%; }
+
+table.function_list {
+    border-width: 1px;
+    border-style: solid;
+    border-color: #aaaaaa;
+    border-collapse: collapse;
+}
+table.function_list td {
+    border-width: 1px;
+    padding: 3px;
+    border-style: solid;
+    border-color: #eeeeee;
+}
+
+table.function_list td.name { background-color: #f0f0ff; }
+
+table.function_list td.summary { width: 100%; }
+
+table.table_list {
+    border-width: 1px;
+    border-style: solid;
+    border-color: #cccccc;
+    border-collapse: collapse;
+}
+table.table_list td {
+    border-width: 1px;
+    padding: 3px;
+    border-style: solid;
+    border-color: #cccccc;
+}
+
+table.table_list td.name { background-color: #f0f0f0; }
+
+table.table_list td.summary { width: 100%; }
+
+dl.table dt, dl.function dt {border-top: 1px solid #ccc; padding-top: 1em;}
+dl.table dd, dl.function dd {padding-bottom: 1em; margin: 10px 0 0 20px;}
+dl.table h3, dl.function h3 {font-size: .95em;}
diff --git a/Data/Libraries/LDoc/tests/example/style/ldoc.ltp b/Data/Libraries/LDoc/tests/example/style/ldoc.ltp
new file mode 100644
index 0000000..24d786a
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/example/style/ldoc.ltp
@@ -0,0 +1,135 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<head>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
+    <title>$(ldoc.title)</title>
+    <link rel="stylesheet" href="$(ldoc.css)" type="text/css" />
+</head>
+<body>
+
+<div id="container">
+
+<div id="product">
+	<div id="product_logo"></div>
+	<div id="product_name"><big><b></b></big></div>
+	<div id="product_description"></div>
+</div> <!-- id="product" -->
+
+<div id="main">
+
+# local iter = ldoc.modules.iter
+# local M = ldoc.markup
+
+<!-- Menu -->
+
+# local function no_spaces(s) return s:gsub('%s','_') end
+# local function use_li(ls)
+#   if #ls > 1 then return '<li>','</li>' else return '','' end
+# end
+# local function display_name(item)
+#   if item.type == 'function' then return item.name..'&nbsp;'..item.args
+#   else return item.name end
+#  end
+
+
+<div id="navigation">
+<h1>$(ldoc.project)</h1>
+# if not ldoc.single then
+<ul>
+  <li><a href="../index.html">Index</a></li>
+</ul>
+# else
+<p>$(M(ldoc.description))</p>
+# end
+
+# if module then
+<hr/>
+<ul>
+# for kind, items in module.kinds() do
+# for item in items() do
+    <li><a href="#$(item.name)">$(display_name(item))</a></li>
+# end
+# end
+</ul>
+# end
+
+</div>
+
+<div id="content">
+
+# if module then
+
+<h1>Module <code>$(module.name)</code></h1>
+
+<p>$(M(module.summary))</p>
+<p>$(M(module.description))</p>
+
+<br/>
+<br/>
+
+# --- currently works for both Functions and Tables. The params field either contains
+# --- function parameters or table fields.
+# for kind, items in module.kinds() do
+    <dl class="function">
+#  for item in items() do
+    <dt>
+    <a name = "$(item.name)"></a>
+    <strong>$(display_name(item))</strong>
+    </dt>
+    <dd>
+    $(M(item.summary))
+    $(M(item.description))
+
+#   if item.usage then
+#     local li,il = use_li(item.usage)
+    <h3>Usage:</h3>
+    <ul>
+#     for usage in iter(item.usage) do
+        $(li)<pre class="example">$(usage)</pre>$(il)
+#     end -- for
+    </ul>
+#   end -- if usage
+
+#   if item.see then
+#     local li,il = use_li(item.see)
+    <h3>see also:</h3>
+    <ul>
+#     for see in iter(item.see) do
+         $(li)<a href="$(see.mod).html#$(see.name)">$(see.label)</a>$(il)
+#    end -- for
+    </ul>
+#   end -- if see
+</dd>
+# end -- for items
+</dl>
+# end -- for kinds
+
+# else -- if module
+
+# if ldoc.description then
+  <p>$(M(ldoc.description))</p>
+# end
+
+# for kind, mods in ldoc.kinds() do
+<h2>$(kind)</h2>
+# kind = kind:lower()
+# for m in mods() do
+<table class="module_list">
+	<tr>
+		<td class="name"><a href="$(no_spaces(kind))/$(m.name).html">$(m.name)</a></td>
+		<td class="summary">$(M(m.summary))</td>
+	</tr>
+#  end -- for modules
+</table>
+# end -- for kinds
+# end -- if module
+
+</div> <!-- id="content" -->
+</div> <!-- id="main" -->
+<div id="about">
+</div> <!-- id="about" -->
+</div> <!-- id="container" -->
+</body>
+</html>
+
diff --git a/Data/Libraries/LDoc/tests/example/style/mod1.lua b/Data/Libraries/LDoc/tests/example/style/mod1.lua
new file mode 100644
index 0000000..9ba0b21
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/example/style/mod1.lua
@@ -0,0 +1,60 @@
+---------------------------
+-- Test module providing bonzo.dog.
+-- Rest is a longer description
+-- @class module
+-- @name mod1
+
+--- zero function. Two new ldoc features here; item types
+-- can be used directly as tags, and aliases for tags
+-- can be defined in config.lp.
+-- @function zero_fun
+-- @p k1 first
+-- @p k2 second
+
+--- first function. Some description
+-- @param p1 first parameter
+-- @param p2 second parameter
+function mod1.first_fun(p1,p2)
+end
+
+-------------------------
+-- second function.
+-- @param ... var args!
+function mod1.second_function(...)
+end
+
+------------
+-- third function. Can also provide parameter comments inline,
+-- provided they follow this pattern.
+function mod1.third_function(
+    alpha, -- correction A
+    beta, -- correction B
+    gamma -- factor C
+    )
+end
+
+-----
+-- A useful macro. This is an example of a custom 'kind'.
+-- @macro first_macro
+-- @see second_function
+
+---- general configuration table
+-- @table config
+-- @field A alpha
+-- @field B beta
+-- @field C gamma
+mod1.config = {
+    A = 1,
+    B = 2,
+    C = 3
+}
+
+--[[--
+Another function. Using a Lua block comment
+@param p a parameter
+]]
+function mod1.zero_function(p)
+end
+
+
+
diff --git a/Data/Libraries/LDoc/tests/example/style/simple.lua b/Data/Libraries/LDoc/tests/example/style/simple.lua
new file mode 100644
index 0000000..e569461
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/example/style/simple.lua
@@ -0,0 +1,51 @@
+---------------
+-- Markdown-flavoured and very simple no-structure style.
+--
+-- Here the idea is to structure the document entirely with [Markdown]().
+--
+-- Using the default markdown processor can be a little irritating: you are
+-- required to give a blank line before starting lists. The default stylesheet
+-- is not quite right, either.
+--
+module 'mod'
+
+--- Combine two strings _first_ and _second_ in interesting ways.
+function combine(first,second)
+end
+
+--- Combine a whole bunch of strings.
+function combine_all(...)
+end
+
+---
+-- Creates a constant capture. This pattern matches the empty string and
+-- produces all given values as its captured values.
+function lpeg.Cc([value, ...]) end
+
+
+--- Split a string _str_. Returns the first part and the second part, so that
+-- `combine(first,second)` is equal to _s_.
+function split(s)
+end
+
+--- Split a string _text_ into a table.
+-- Returns:
+--
+-- - `name` the name of the text
+-- - `pairs` an array of pairs
+--    - `key`
+--    - `value`
+--  - `length`
+--
+
+function split_table (text)
+end
+
+--- A table of useful constants.
+--
+-- - `alpha` first correction factor
+-- - `beta` second correction factor
+--
+-- @table constants
+
+
diff --git a/Data/Libraries/LDoc/tests/factory/factory.lua b/Data/Libraries/LDoc/tests/factory/factory.lua
new file mode 100644
index 0000000..e620ee0
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/factory/factory.lua
@@ -0,0 +1,51 @@
+---
+-- Useful classes.
+-- This is the enclosing module description.
+
+--- My class.
+-- Describe our class
+-- @factory Object
+
+local make_object
+do
+  --- my private method
+  -- document here. (By default it will not show in docs.)
+  -- @private
+  local my_private_method = function(self)
+    ...more code here...
+  end
+
+  --- my public method.
+  -- documentation here
+  -- @param arg
+  local method = function(self, arg)
+     .....some code here.....
+     return my_private_method(self)
+  end
+
+   --- Another public method.
+   -- More details
+   local more = function(self)
+   end
+
+  --- factory returning @{Object}.
+  -- @constructor
+  -- @param arg
+  -- @param arg2
+  make_object = function(arg, arg2)
+    return
+    {
+      -- private fields
+      field_ = arg;
+
+      -- public methods
+      method = method;
+      more = more;
+    }
+  end
+end
+
+return {
+    make_object = make_object
+}
+
diff --git a/Data/Libraries/LDoc/tests/factory/mymod.lua b/Data/Libraries/LDoc/tests/factory/mymod.lua
new file mode 100644
index 0000000..d872047
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/factory/mymod.lua
@@ -0,0 +1,21 @@
+--- mymod
+
+local mymod = {}
+
+--- everything!
+function mymod.query (
+    a, --string: first arg
+    b, --int: second arg
+    c  --table: arg
+)
+end
+
+
+--- for everything.
+function mymod.answer (
+    a, -- first arg
+    b, -- second arg
+    c)  -- third arg
+end
+
+return mymod
diff --git a/Data/Libraries/LDoc/tests/funmod.lua b/Data/Libraries/LDoc/tests/funmod.lua
new file mode 100644
index 0000000..f9eaef2
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/funmod.lua
@@ -0,0 +1,13 @@
+-------
+-- Summing values.
+-- Returns a single function.
+-- @param a first
+-- @param b second
+-- @param c third
+-- @return sum of parameters
+-- @module funmod
+
+return function(a,b,c)
+   return a + b + c
+end
+
diff --git a/Data/Libraries/LDoc/tests/luadoc/config.ld b/Data/Libraries/LDoc/tests/luadoc/config.ld
new file mode 100644
index 0000000..4f4e7aa
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/luadoc/config.ld
@@ -0,0 +1,5 @@
+project = 'LuaDoc'
+title = "LuaDoc with LDoc"
+package = 'luadoc'
+-- point this to your Luarocks directory
+file = [[c:\lua\lua\luadoc]]
diff --git a/Data/Libraries/LDoc/tests/md-test/config.ld b/Data/Libraries/LDoc/tests/md-test/config.ld
new file mode 100644
index 0000000..0c45580
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/md-test/config.ld
@@ -0,0 +1,5 @@
+project = 'md-test'
+title = 'Markdown Docs'
+format = 'markdown'
+file = 'mod2.lua'
+
diff --git a/Data/Libraries/LDoc/tests/md-test/mod2.lua b/Data/Libraries/LDoc/tests/md-test/mod2.lua
new file mode 100644
index 0000000..4e73671
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/md-test/mod2.lua
@@ -0,0 +1,25 @@
+---------------------
+-- Another test module.
+-- This one uses _Markdown_ formating, and
+-- so can include goodies such as `code`
+-- and lists:
+--
+--  - one
+--  - two
+--  - three
+--
+-- @module mod2
+
+--- really basic function. Can contain links such as
+-- [this](http://lua-users.org/wiki/FindPage)
+-- @param first like `gsb(x)`
+-- @param second **bold** maybe? It can continue:
+--
+--  - another point
+--  - finish the damn list
+-- @param third as before
+function mod2.basic(first,second,third)
+
+end
+
+
diff --git a/Data/Libraries/LDoc/tests/merge/config.ld b/Data/Libraries/LDoc/tests/merge/config.ld
new file mode 100644
index 0000000..f08e90c
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/merge/config.ld
@@ -0,0 +1,2 @@
+merge=true
+file={'merge1.lua','merge2.lua'}
diff --git a/Data/Libraries/LDoc/tests/merge/merge1.lua b/Data/Libraries/LDoc/tests/merge/merge1.lua
new file mode 100644
index 0000000..3bdbc36
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/merge/merge1.lua
@@ -0,0 +1,7 @@
+----
+-- main module
+-- @module merge
+
+---- first fun
+function one()
+end
diff --git a/Data/Libraries/LDoc/tests/merge/merge2.lua b/Data/Libraries/LDoc/tests/merge/merge2.lua
new file mode 100644
index 0000000..02bc63c
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/merge/merge2.lua
@@ -0,0 +1,19 @@
+----
+-- submodule
+-- @module merge
+
+---- second fun
+-- @param x
+function two(x)
+end
+
+--- extra stuff
+-- @section extra
+
+--- third fun
+function three ()
+end
+
+--- fourth fun
+function four ()
+end
diff --git a/Data/Libraries/LDoc/tests/mod1.ld b/Data/Libraries/LDoc/tests/mod1.ld
new file mode 100644
index 0000000..42a6e53
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/mod1.ld
@@ -0,0 +1,9 @@
+-- ldoc -c mod1.ld .
+project = 'mod1'
+description = 'showing various ldoc comment styles'
+title = 'mod docs'
+-- may be a table containing files and directories
+file = 'mod1.lua'
+-- show local functions as well!
+all = true  
+
diff --git a/Data/Libraries/LDoc/tests/mod1.lua b/Data/Libraries/LDoc/tests/mod1.lua
new file mode 100644
index 0000000..a1156c2
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/mod1.lua
@@ -0,0 +1,46 @@
+------
+-- always need a doc comment to start!
+-- Can have a module with no internal doc comments,
+-- although you will get a warning. At least we no
+-- longer get a 'end-of-file' if there is no explicit
+-- module name.
+
+----- not a doc comment -----
+-- a common style when just specifying an informative comment
+-- May start with a doc comment but has trailing hyphens
+
+local g -- so g below must be marked as local
+
+--- simple.
+--@param x a parameter
+function _M.f(x) end
+
+--- implicit local function.
+-- Local functions appear in dump but only in docs if you say --all
+local function L(t,v) end
+
+--- explicit local function.
+-- @local here
+function g(a,b) end
+
+--- a table of this module
+_M.contents = {
+    A = 'f', -- alpha
+    B = 'g'  -- beta
+}
+
+--- another way to do parameters.
+function _M.kay(
+    a, -- ay
+    b, -- bee
+) end
+
+--- a field of this module.
+_M.constant = 'hello'
+
+--- functions can also be like so.
+_M.why = function(x,y)
+end
+
+
+
diff --git a/Data/Libraries/LDoc/tests/moonscript/List.moon b/Data/Libraries/LDoc/tests/moonscript/List.moon
new file mode 100644
index 0000000..bd1272e
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/moonscript/List.moon
@@ -0,0 +1,65 @@
+----
+-- A list class that wraps a table
+-- @classmod List
+import insert,concat,remove from table
+
+class List
+    --- constructor passed a table `t`, which can be `nil`.
+    new: (t) =>
+        @ls = t or {}
+
+    --- append to list.
+    add: (item) =>
+        insert @ls,item
+
+    --- insert `item` at `idx`
+    insert: (idx,item) =>
+        insert @ls,idx,item
+
+    --- remove item at `idx`
+    remove: (idx) => remove @ls,idx
+
+    --- length of list
+    len: => #@ls
+
+    --- string representation
+    __tostring: => '['..(concat @ls,',')..']'
+
+    --- return idx of first occurence of `item`
+    find: (item) =>
+        for i = 1,#@ls
+            if @ls[i] == item then return i
+
+    --- remove item by value
+    remove_value: (item) =>
+        idx = self\find item
+        self\remove idx if idx
+
+    --- remove a list of items
+    remove_values: (items) =>
+        for item in *items do self\remove_value item
+
+    --- create a sublist of items indexed by a table `indexes`
+    index_by: (indexes) =>
+        List [@ls[idx] for idx in *indexes]
+
+    --- make a copy of this list
+    copy: => List [v for v in *@ls]
+
+    --- append items from the table or list `list`
+    extend: (list) =>
+        other = if list.__class == List then list.ls else list
+        for v in *other do self\add v
+        self
+
+    --- concatenate two lists, giving a new list
+    __concat: (l1,l2) -> l1\copy!\extend l2
+
+    --- an iterator over all items
+    iter: =>
+        i,t,n = 0,@ls,#@ls
+        ->
+            i += 1
+            if i <= n then t[i]
+
+return List
diff --git a/Data/Libraries/LDoc/tests/moonscript/config.ld b/Data/Libraries/LDoc/tests/moonscript/config.ld
new file mode 100644
index 0000000..7b7763b
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/moonscript/config.ld
@@ -0,0 +1,5 @@
+file = 'List.moon'
+no_return_or_parms=true
+no_summary=true
+format = 'markdown'
+--sort = true
diff --git a/Data/Libraries/LDoc/tests/one.md b/Data/Libraries/LDoc/tests/one.md
new file mode 100644
index 0000000..c27292c
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/one.md
@@ -0,0 +1,11 @@
+# Documentation
+
+## types
+
+A reference to @{types.first}
+
+A `first` topic
+
+## classes
+
+A `second` topic
diff --git a/Data/Libraries/LDoc/tests/simple/problem.lua b/Data/Libraries/LDoc/tests/simple/problem.lua
new file mode 100644
index 0000000..3848539
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/simple/problem.lua
@@ -0,0 +1,19 @@
+--- this module has a comment.
+
+local local_two
+
+--- a local function
+local function local_one ()
+end
+
+--- a local function, needing explicit tag.
+-- @local here
+function local_two ()
+
+end
+
+--- A problem function.
+-- @param p a parameter
+function problem.fun(p)
+    return 42
+end
diff --git a/Data/Libraries/LDoc/tests/simple/simple.lua b/Data/Libraries/LDoc/tests/simple/simple.lua
new file mode 100644
index 0000000..15d2a39
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/simple/simple.lua
@@ -0,0 +1,12 @@
+------------
+-- A little old-style module
+local io = io
+-- we'll look for this
+module 'simple'
+
+-- if it were 'module (...)' then the name has to be deduced.
+
+--- return the answer.
+function answer()
+  return 42
+end
diff --git a/Data/Libraries/LDoc/tests/simple/simple_alias.lua b/Data/Libraries/LDoc/tests/simple/simple_alias.lua
new file mode 100644
index 0000000..72d17af
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/simple/simple_alias.lua
@@ -0,0 +1,16 @@
+------------
+-- A new-style module.
+-- Shows how @alias can be used to tell ldoc that a given name
+-- is a shorthand for the full module name
+-- @alias M
+
+local simple_alias = {}
+local M = simple_alias
+
+--- return the answer. And complete the description
+function M.answer()
+  return 42
+end
+
+return simple_alias
+
diff --git a/Data/Libraries/LDoc/tests/simple/tables.lua b/Data/Libraries/LDoc/tests/simple/tables.lua
new file mode 100644
index 0000000..bdc612d
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/simple/tables.lua
@@ -0,0 +1,39 @@
+------------
+-- A module containing tables.
+-- Shows how Lua table definitions can be conveniently parsed.
+--
+-- There may be multiple comment lines per field/parameter, and
+-- such comments may begin with `TYPE:`
+--
+-- Functions also can be commented in a similar way, and the last
+-- parameter's comment may be outside the parens.
+--
+-- @alias M
+
+local tables = {}
+local M = tables
+
+--- a function.
+function M.one(
+    bonzo, -- dog
+           -- has its day!
+    frodo) --baggins
+end
+
+--- first table.
+-- @table one
+M.one = {
+    A = 1, -- alpha
+    B = 2; -- beta
+}
+
+--- second table.
+-- we don't need an explicit table tag, since it
+-- can be inferred from the context.
+M.two = {
+    N = 10,  -- int: no. of cases
+    L = 'label' -- string: case label
+}
+
+return M
+
diff --git a/Data/Libraries/LDoc/tests/styles/colon.lua b/Data/Libraries/LDoc/tests/styles/colon.lua
new file mode 100644
index 0000000..bb3ffea
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/styles/colon.lua
@@ -0,0 +1,35 @@
+----------------------
+-- Showing off Colon mode.
+-- If you hate @ tags, you can use colons. However, you need to specify colon
+-- mode explicitly -C or --colon, or `colon=true` in the config.ld. Be careful
+-- not to use a colon followed by a space for any other purpose!
+--
+-- So the incantation in this case is `ldoc -C colon.lua`.
+
+-- module: colon
+
+
+--- first useless function.
+-- Optional type specifiers are allowed in this format.
+-- As an extension, '?T' is short for '?nil|T'.
+-- Note how these types are rendered!
+-- string: name
+-- int: age
+-- ?person3: options
+-- treturn: ?table|string
+function one (name,age,options)
+end
+
+--- implicit table can always use colon notation.
+person2 = {
+    id=true, -- string: official ID number
+    sex=true, -- string: one of 'M', 'F' or 'N'
+    spouse=true, -- ?person3: wife or husband
+}
+
+--- explicit table in colon format.
+-- Note how '!' lets you use a type name directly.
+-- string: surname
+-- string: birthdate
+-- !person2: options
+-- table: person3
diff --git a/Data/Libraries/LDoc/tests/styles/config/config.ld b/Data/Libraries/LDoc/tests/styles/config/config.ld
new file mode 100644
index 0000000..d70b7bb
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/styles/config/config.ld
@@ -0,0 +1,2 @@
+no_return_or_parms=true
+no_summary=true
diff --git a/Data/Libraries/LDoc/tests/styles/four.lua b/Data/Libraries/LDoc/tests/styles/four.lua
new file mode 100644
index 0000000..09f3bf0
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/styles/four.lua
@@ -0,0 +1,59 @@
+------------
+-- Yet another module.
+-- Description can continue after simple tags, if you
+-- like - but to keep backwards compatibility, say 'not_luadoc=true'
+-- @module four
+-- @author bob, james
+-- @license MIT
+-- @copyright InfoReich 2013
+
+--- a function with typed args.
+-- Note the the standard tparam aliases, and how the 'opt' and 'optchain'
+-- modifiers may also be used. If the Lua function has varargs, then
+-- you may document an indefinite number of extra arguments!
+-- @tparam ?string|Person name person's name
+-- @int age
+-- @string[opt='gregorian'] calender optional calendar
+-- @int[opt=0] offset optional offset
+-- @treturn string
+-- @see file:write
+function one (name,age,...)
+end
+
+---- testing [opt]
+-- @param one
+-- @param[opt] two
+-- @param three
+-- @param[opt] four
+function two (one,two,three,four)
+end
+
+--- third useless function.
+-- Can always put comments inline, may
+-- be multiple.
+-- note that first comment refers to return type!
+function three ( -- person:
+    name, -- string: person's name
+    age  -- int:
+        -- not less than zero!
+)
+end
+
+---- function with single optional arg
+-- @param[opt] one
+function four (one)
+end
+
+--- an implicit table.
+-- Again, we can use the comments
+person = {
+    name = '', -- string: name of person
+    age = 0, -- int:
+}
+
+--- an explicit table.
+-- Can now use tparam aliases in table defns
+-- @string name
+-- @int age
+-- @table person2
+
diff --git a/Data/Libraries/LDoc/tests/styles/func.lua b/Data/Libraries/LDoc/tests/styles/func.lua
new file mode 100644
index 0000000..ef05845
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/styles/func.lua
@@ -0,0 +1,15 @@
+------------
+-- Get length of string.
+-- A (silly) module which returns a single function
+--
+-- @module func
+-- @string some text
+-- @param opts multibyte encoding options
+-- @string opts.charset encoding used
+-- @bool opts.strict be very pedantic
+-- @bool verbose tell the world about everything
+-- @return its length
+return function(s,opts,verbose)
+    return #s
+end
+
diff --git a/Data/Libraries/LDoc/tests/styles/multiple.lua b/Data/Libraries/LDoc/tests/styles/multiple.lua
new file mode 100644
index 0000000..85e12b9
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/styles/multiple.lua
@@ -0,0 +1,45 @@
+------
+-- Various ways of indicating errors
+-- @module multiple
+
+-----
+-- function with return groups.
+-- @treturn[1] string result
+-- @return[2]  nil
+-- @return[2] error message
+function mul1 () end
+
+-----
+-- function with return and  error tag
+-- @return  result
+-- @error message
+function mul2 () end
+
+-----
+-- function with multiple error tags
+-- @return  result
+-- @error not found
+-- @error bad format
+function mul3 () end
+
+----
+-- function with inline return and errors
+-- @string name
+function mul4 (name)
+    if type(name) ~= 'string' then
+        --- @error[1] not a string
+        return nil, 'not a string'
+    end
+    if #name == 0 then
+        --- @error[2] zero-length string
+        return nil, 'zero-length string'
+    end
+    --- @treturn string converted to uppercase
+    return name:upper()
+end
+-----
+-- function that raises an error.
+-- @string filename
+-- @treturn string result
+-- @raise 'file not found'
+function mul5(filename) end
diff --git a/Data/Libraries/LDoc/tests/styles/one.lua b/Data/Libraries/LDoc/tests/styles/one.lua
new file mode 100644
index 0000000..30e3145
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/styles/one.lua
@@ -0,0 +1,23 @@
+--[[
+A non-doc comment
+multi-line
+probably containing license information!
+Doesn't use module(), but module name is inferred from file name.
+If you have initial licence comments that look like doc comments,
+then set `boilerplate=true`
+]]
+------------
+-- Test module,
+-- Actual blurb here!
+----
+
+local one = {}
+
+--- answer to everything.
+function one.answer ()
+    return 42
+end
+
+return one
+
+
diff --git a/Data/Libraries/LDoc/tests/styles/opt.ld b/Data/Libraries/LDoc/tests/styles/opt.ld
new file mode 100644
index 0000000..0895ddc
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/styles/opt.ld
@@ -0,0 +1,11 @@
+-- must have explicit optchain!
+convert_opt = true
+
+format = 'markdown'
+
+-- want to include project source as well.
+prettify_files = 'show'
+
+-- a custom tag!
+custom_tags = {{'remark',title='Remarks'}}
+
diff --git a/Data/Libraries/LDoc/tests/styles/opt.lua b/Data/Libraries/LDoc/tests/styles/opt.lua
new file mode 100644
index 0000000..6cdba2d
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/styles/opt.lua
@@ -0,0 +1,21 @@
+------------
+-- ### Functions with options and custom tags.
+-- (use `ldoc -c opt.ld opt.lua` for converting.)
+--
+-- @include opt.md
+
+---- testing [opt]
+-- @param one
+-- @param[opt] two
+-- @param[opt] three
+-- @param[opt] four
+-- @remark use with caution!
+function use_opt (one,two,three,four)
+end
+
+--- an explicit table.
+-- Can use tparam aliases in table defns
+-- @string name
+-- @int[opt=0] age
+-- @table person2
+
diff --git a/Data/Libraries/LDoc/tests/styles/opt.md b/Data/Libraries/LDoc/tests/styles/opt.md
new file mode 100644
index 0000000..256f6b2
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/styles/opt.md
@@ -0,0 +1,9 @@
+By default, an unbroken series of opt modifiers is converted to
+'opt','optchain','optchain', so you get `(a[,b[,c])`.
+
+If `convert_opt` is specified, then no such conversion takes place; you then 
+must explicitly use `optchain`.
+
+The `@include` tag is only meaningful for project-level items like modules,
+scripts, etc. The file is inserted into the document after being formatted.
+In this case, you would usually specify `format="markdown"`.
diff --git a/Data/Libraries/LDoc/tests/styles/priority_queue.lua b/Data/Libraries/LDoc/tests/styles/priority_queue.lua
new file mode 100644
index 0000000..9dcc5ad
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/styles/priority_queue.lua
@@ -0,0 +1,101 @@
+--------------------------------------------------------------------------------
+--- Queue of objects sorted by priority.
+-- @module lua-nucleo.priority_queue
+-- This file is a part of lua-nucleo library. Note that if you wish to spread
+-- the description after tags, then invoke with `not_luadoc=true`. 
+-- The flags here are `ldoc -X -f backtick priority_queue.lua`, which
+-- also expands backticks.
+-- @copyright lua-nucleo authors (see file `COPYRIGHT` for the license)
+--------------------------------------------------------------------------------
+
+local arguments,
+      method_arguments
+      = import 'lua-nucleo/args.lua'
+      {
+        'arguments',
+        'method_arguments'
+      }
+
+local lower_bound_gt
+      = import 'lua-nucleo/algorithm.lua'
+      {
+        'lower_bound_gt'
+      }
+
+--------------------------------------------------------------------------------
+
+local table_insert, table_remove = table.insert, table.remove
+
+--------------------------------------------------------------------------------
+
+--- Priority Queue
+-- @factory priority_queue
+local make_priority_queue
+do
+  local PRIORITY_KEY = 1
+  local VALUE_KEY = 2
+
+  local insert = function(self, priority, value)
+    method_arguments(
+        s
+        "number", priority
+      )
+    assert(value ~= nil, "value can't be nil") -- value may be of any type, except nil
+
+    local queue = self.queue_
+    local k = lower_bound_gt(queue, PRIORITY_KEY, priority)
+
+    table_insert(queue, k, { [PRIORITY_KEY] = priority, [VALUE_KEY] = value })
+  end
+
+  local front = function(self)
+    method_arguments(
+        self
+      )
+
+    local queue = self.queue_
+    local front_elem = queue[#queue]
+
+    if front_elem == nil then
+      return nil
+    end
+
+    return front_elem[PRIORITY_KEY], front_elem[VALUE_KEY]
+  end
+
+  --- pop last value.
+  -- @return priority
+  -- @return value
+  local pop = function(self)
+    method_arguments(
+        self
+      )
+
+    local front_elem = table_remove(self.queue_)
+
+    if front_elem == nil then
+      return nil
+    end
+
+    return front_elem[PRIORITY_KEY], front_elem[VALUE_KEY]
+  end
+
+  --- construct a `priority_queue`.
+  -- @constructor
+  make_priority_queue = function()
+    --- @export
+    return
+    {
+      insert = insert;
+      front = front;
+      pop = pop;
+      --
+      queue_ = { };
+    }
+  end
+end
+
+return
+{
+  make_priority_queue = make_priority_queue;
+}
diff --git a/Data/Libraries/LDoc/tests/styles/struct.lua b/Data/Libraries/LDoc/tests/styles/struct.lua
new file mode 100644
index 0000000..c28689a
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/styles/struct.lua
@@ -0,0 +1,13 @@
+------
+-- functions returning compound types
+-- @module struct
+
+-----
+-- returns a 'struct'.
+-- @string name your name dammit
+-- @tfield string arb stuff
+-- @treturn st details of person
+-- @tfield[st] string name of person
+-- @tfield[st] int age of person
+function struct(name) end
+
diff --git a/Data/Libraries/LDoc/tests/styles/subparams.lua b/Data/Libraries/LDoc/tests/styles/subparams.lua
new file mode 100644
index 0000000..0e5e17e
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/styles/subparams.lua
@@ -0,0 +1,17 @@
+------------
+-- Parameters may have named subfields, if they are tables.
+--
+-- @module subparams
+module(...)
+
+-------
+-- A function with subfield arguments.
+-- @param s string
+-- @param opts multibyte encoding options
+-- @param opts.charset string
+-- @param opts.strict bool
+-- @param verbose bool
+-- @return its length
+function with_options (s,opts,verbose)
+end
+
diff --git a/Data/Libraries/LDoc/tests/styles/three.lua b/Data/Libraries/LDoc/tests/styles/three.lua
new file mode 100644
index 0000000..09c0ceb
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/styles/three.lua
@@ -0,0 +1,21 @@
+------------
+-- Alternative to no-magic style.
+-- Description here
+----
+
+--- documented, but private
+local function question ()
+end
+
+--- answer to everything.
+-- @return magic number
+local function answer ()
+    return 42
+end
+
+--- @export
+return {
+    answer = answer
+}
+
+
diff --git a/Data/Libraries/LDoc/tests/styles/two.lua b/Data/Libraries/LDoc/tests/styles/two.lua
new file mode 100644
index 0000000..3976ed3
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/styles/two.lua
@@ -0,0 +1,13 @@
+------------
+-- Classic Lua 5.1 module.
+-- Description here
+----
+
+module 'two'
+
+--- answer to everything.
+function answer ()
+    return 42
+end
+
+
diff --git a/Data/Libraries/LDoc/tests/styles/type.lua b/Data/Libraries/LDoc/tests/styles/type.lua
new file mode 100644
index 0000000..cde0dd7
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/styles/type.lua
@@ -0,0 +1,45 @@
+-----
+-- module containing a class
+-- @module type
+
+----
+-- Our class. Any function or table in this section belongs to `Bonzo`
+-- @type Bonzo
+
+----
+-- make a new Bonzo.
+-- @see Bonzo:dog
+-- @string s name of Bonzo
+function Bonzo.new(s)
+end
+
+-----
+-- get a string representation.
+-- works with `tostring`
+function Bonzo:__tostring()
+end
+
+----
+-- Another method.
+function Bonzo:dog ()
+
+end
+
+----
+-- Private method.
+-- You need -a flag or 'all=true' to see these
+-- @local
+function Bonzo:cat ()
+
+end
+
+
+----
+-- A subtable with fields.
+-- @table Details
+-- @string[readonly] name
+-- @int[readonly] age
+
+---
+-- This is a simple field/property of the class.
+-- @string[opt="Bilbo",readonly] frodo direct access to text
diff --git a/Data/Libraries/LDoc/tests/styles/x.c b/Data/Libraries/LDoc/tests/styles/x.c
new file mode 100644
index 0000000..fc8dffc
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/styles/x.c
@@ -0,0 +1,46 @@
+/***************
+ * First comment is ignored,
+ * containing licenses, warnings,
+ * old-fashioned commit info and so forth
+ */
+
+/** No-brainer C extension.
+Description as before.
+@module x
+*/
+#include <lua.h>
+#include <lauxlib.h>
+#include <lualib.h>
+
+/***
+@string name
+@int age
+@table output
+*/
+
+/***
+Create a table with given array and hash slots.
+Note that we can't (yet) deduce the name of
+the Lua function.
+@function createtable
+@param narr initial array slots, default 0
+@param nrec initial hash slots, default 0
+@return table
+*/
+static int l_createtable (lua_State *L) {
+  int narr = luaL_optint(L,1,0);
+  int nrec = luaL_optint(L,2,0);
+  lua_createtable(L,narr,nrec);
+  return 1;
+}
+
+static const luaL_reg x[] = {
+    {"createtable",l_createtable},
+    {NULL,NULL}
+};
+
+int luaopen_x(lua_State *L)
+{
+    luaL_register (L, "x", x);
+    return 1;
+}
diff --git a/Data/Libraries/LDoc/tests/submodule/config.ld b/Data/Libraries/LDoc/tests/submodule/config.ld
new file mode 100644
index 0000000..8369015
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/submodule/config.ld
@@ -0,0 +1,2 @@
+file = {'mylib/init.lua','mylib/extra.lua'}
+if foo then print 'foo' end
diff --git a/Data/Libraries/LDoc/tests/submodule/mylib/extra.lua b/Data/Libraries/LDoc/tests/submodule/mylib/extra.lua
new file mode 100644
index 0000000..bb06b40
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/submodule/mylib/extra.lua
@@ -0,0 +1,13 @@
+-----------
+-- Extra module
+-- @submodule mylib
+
+--- will appear in mylib's docs!
+function E ()
+
+end
+
+--- ditto
+function F ()
+
+end
diff --git a/Data/Libraries/LDoc/tests/submodule/mylib/init.lua b/Data/Libraries/LDoc/tests/submodule/mylib/init.lua
new file mode 100644
index 0000000..83bc90a
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/submodule/mylib/init.lua
@@ -0,0 +1,35 @@
+-----------
+-- Main module.
+-- This contains four functions, two of which are in
+-- another section implicitly specified using the 'within' tag.
+-- (This allows functions placed together to be classified
+-- separately)
+--
+-- Furthermore, the 'mylib.extra' functions will be added
+-- as their own section, allowing you to document a logical module
+-- spanning several files
+--
+-- @module mylib
+
+--- first.
+function A ()
+
+end
+
+--- second, within its own section.
+-- @within Utilities
+function B ()
+
+end
+
+--- third.
+function C ()
+
+end
+
+--- fourth, together with second.
+-- @within Utilities
+function D ()
+
+end
+
diff --git a/Data/Libraries/LDoc/tests/two.md b/Data/Libraries/LDoc/tests/two.md
new file mode 100644
index 0000000..0b2c3a9
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/two.md
@@ -0,0 +1,9 @@
+# And another
+
+## First
+
+A `first` topic
+
+## Second
+
+A `second` topic
diff --git a/Data/Libraries/LDoc/tests/types.lua b/Data/Libraries/LDoc/tests/types.lua
new file mode 100644
index 0000000..7555608
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/types.lua
@@ -0,0 +1,34 @@
+-----------------------
+-- Module using tparam for typed parameters.
+--
+-- @module types
+
+--- has typed parameters, `string` and `int`.
+-- And never forget `E = m*c^2`.
+-- Reference to `two.md.First`
+--
+-- A reference to `mydata`.
+-- @string name
+-- @int age
+-- @treturn mydata
+function _M.first (name,age)
+
+end
+
+--- simple function returning something
+-- @return bonzo dog!
+function _M.simple()
+
+end
+
+
+--- a table of this module.
+-- @table mydata
+_M.mydata = {
+    one = 1, -- alpha
+    two = 2, -- beta
+}
+
+
+
+
diff --git a/Data/Libraries/LDoc/tests/underscore.lua b/Data/Libraries/LDoc/tests/underscore.lua
new file mode 100644
index 0000000..442a778
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/underscore.lua
@@ -0,0 +1,39 @@
+--[[-----------
+ testing underscores and Markdown pre-formatting.
+
+ A list may immediately follow a line, if it is indented. Necessary lines
+ will also be inserted after resuming current indentation.
+  - a list
+     - sublist (note the needed indentation for Markdown to recognize this)
+     - more
+  * of items
+  more than one line
+  - indeed
+  can keep going
+Inline _see references_: look at @{_ONE_} and @{table.concat}.
+Indented code blocks may also follow immediately.
+    function test(a,b)
+       return three(a,b)
+    end
+ @module underscore
+]]
+
+----------
+-- A function.
+-- Can also use @{_TWO_ |second function}
+function _ONE_() end
+
+-----------
+-- another function
+-- @see string.format
+function _TWO_() end
+
+------
+-- a longer summary.
+-- @param a
+-- @param b
+-- @return one
+-- - one-1
+-- - one-2
+-- @return two
+function three(a,b) end
diff --git a/Data/Libraries/LDoc/tests/usage/config.ld b/Data/Libraries/LDoc/tests/usage/config.ld
new file mode 100644
index 0000000..f33e4ba
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/usage/config.ld
@@ -0,0 +1,15 @@
+project = 'usage'
+file = 'usage.lua'
+examples='usage.lua'
+-- can specify the Markdown processor (falls back to markdown.lua)
+format='markdown'
+-- if you don't use markdown you may wish for backticks to be
+-- expanded if they enclose a reference.
+backtick_references = true
+-- and the prettifier - this will use lxsh _if_ available
+pretty='lxsh'
+-- suppress @params and the summary at the top
+no_return_or_parms=true
+no_summary=true
+not_luadoc=true
+
diff --git a/Data/Libraries/LDoc/tests/usage/usage.lua b/Data/Libraries/LDoc/tests/usage/usage.lua
new file mode 100644
index 0000000..ba05136
--- /dev/null
+++ b/Data/Libraries/LDoc/tests/usage/usage.lua
@@ -0,0 +1,87 @@
+--[[--------
+A simple module with examples.
+
+Even without markdown formatting, blank lines are respected.
+
+@module usage
+]]
+
+local usage = {}
+
+local helper
+
+--- a local helper function.
+-- @local
+function helper ()
+end
+
+----------
+-- A simple vector class.
+--
+-- Supports arithmetic operations.
+-- @usage
+-- v = Vector.new {10,20,30}
+-- assert (v == Vector{10,20,30})
+-- @type Vector
+
+local Vector = {}
+usage.Vector = {}
+
+
+----------
+-- Create a vector from an array `t`.
+-- `Vector` is also callable!
+function Vector.new (t)
+end
+
+-- note that @function may have modifiers. Currently
+-- we aren't doing anything with them, but LDoc no longer
+-- complains (issue #45). Note also that one needs
+-- explicit @param tags with explicit @function; 'static'
+-- methods must have a @constructor or a @static tag.
+
+----------
+-- Create a vector from a string.
+-- @usage
+--  v = Vector.parse '[1,2,3]'
+--  assert (v == Vector.new {1,2,3})
+-- @function[kind=ctor] parse
+-- @static
+-- @param s
+function Vector.parse (s)
+end
+
+--------
+-- Compare two vectors for equality.
+function Vector:__eq (v)
+end
+
+----------
+-- Add another vector, array or scalar `v` to this vector.
+-- Returns new `Vector`
+-- @usage assert(Vector.new{1,2,3}:add(1) == Vector{2,3,4})
+function Vector:add (v)
+end
+
+----------
+-- set vector options. `opts` is a `Vector.Opts` table.
+function Vector:options (opts)
+end
+
+--[[-----------------
+@table Vector.Opts
+Options table format for `Vector:options`
+
+ * `autoconvert`:  try to convert strings to numbers
+ * `adder`: function used to perform addition and subtraction
+ * `multiplier`: function used to perform multiplication and division
+
+@usage
+    v = Vector {{1},{2}}
+    v:options {adder = function(x,y) return {x[1]+y[1]} end}
+    assert(v:add(1) == Vector{{2},{3}})
+]]
+
+return usage
+
+