16 files changed, 476 insertions, 0 deletions
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;
+}