Package list lua-ldoc / 471526a
Merge version 1.4.0 Julian Wollrath 8 years ago
28 changed file(s) with 619 addition(s) and 212 deletion(s). Raw diff Collapse all Expand all
11 title='LDoc documentation'
22 description='A Lua documentation tool'
33 format='discount'
4 backtick_references=false
45 file='../ldoc.lua'
56 dir='../out'
67 readme='doc.md'
8 examples = {'../tests/styles/colon.lua','../tests/styles/four.lua','../tests/example/mylib.c'}
9
213213 contains the documentation for that module, since an index pointing to one module would be
214214 redundant.
215215
216 (If you want to document a script, there is a project-level type 'script' for that.)
216 LDoc has a two-layer hierarchy; underneath the project, there are modules, scripts, classes
217 (containing code) and examples and 'topics' (containing documentation). These then contain
218 items like functions, tables, sections, and so forth.
219
220 If you want to document scripts, then use `@script` instead of `@module`. New with 1.4 is
221 `@classmod` which is a module which exports a single class.
222
217223
218224 ## See References
219225
220226 The tag 'see' is used to reference other parts of the documentation, and 'usage' can provide
221 examples of use:
227 examples of use; there can be multiple such tags:
222228
223229 ---------
224230 -- split a string in two.
256262 Lua standard function or table, and links to the online Lua manual. So references like
257263 'table.concat' are handled sensibly.
258264
259 References may be made inline using the @\{ref} syntax. This may appear anywhere in the
260 text, and is more flexible than @see. In particular, it provides one way to document the
265 References may be made inline using the `@{\ref}` syntax. This may appear anywhere in the
266 text, and is more flexible than `@see`. In particular, it provides one way to document the
261267 type of a parameter or return value when that type has a particular structure:
262268
263269 ------
264270 -- extract standard variables.
265271 -- @param s the string
266 -- @return @\{stdvars}
272 -- @return @{\stdvars}
267273 function extract_std(s) ... end
268274
269275 ------
270276 -- standard variables.
271 -- Use @\{extract_std} to parse a string containing variables,
272 -- and @\{pack_std} to make such a string.
277 -- Use @{\extract_std} to parse a string containing variables,
278 -- and @{\pack_std} to make such a string.
273279 -- @field length
274280 -- @field duration
275281 -- @field viscosity
276282 -- @table stdvars
277283
278 @\{ref} is very useful for referencing your API from code samples and readme text. (I've had
279 to throw in a spurious backspace to stop expansion in this example.)
280
281 The link text can be changed from the default by the extended syntax @\{ref|text}.
284 `@{\ref}` is very useful for referencing your API from code samples and readme text.
285
286 The link text can be changed from the default by the extended syntax `@{\ref|text}.
282287
283288 You can also put references in backticks, like `\`stdvars\``. This is commonly used in
284289 Markdown to indicate code, so it comes naturally when writing documents. It is controlled by
310315 return name, url
311316 end)
312317
313 '^(%a+)%((%d)%)$' both matches the pattern and extracts the name and its section. THen it's
318 '^(%a+)%((%d)%)$' both matches the pattern and extracts the name and its section. Then it's
314319 a simple matter of building up the appropriate URL. The function is expected to
315320 return _link text_ and _link source_ and the patterns are checked before LDoc tries to resolve
316321 project references. So it is best to make them match as exactly as possible.
317322
318323 ## Sections
319324
320 LDoc supports _explicit_ sections. By default, the sections correspond to the pre-existing
325 LDoc supports _explicit_ sections. By default, the implicit sections correspond to the pre-existing
321326 types in a module: 'Functions', 'Tables' and 'Fields' (There is another default section
322327 'Local Functions' which only appears if LDoc is invoked with the `--all` flag.) But new
323 sections can be added; the first mechanism is when you define a new type (say 'macro') a new
324 section ('Macros') is created to contain these types. There is also a way to declare ad-hoc
325 sections using the `@section` tag.
326
328 sections can be added; the first mechanism is when you define a new type (say 'macro'). Then a new
329 section ('Macros') is created to contain these types.
330
331 There is also a way to declare ad-hoc sections using the `@section` tag.
327332 The need occurs when a module has a lot of functions that need to be put into logical
328333 sections.
329334
441446
442447 In this style, types may be used directly if prefixed with '!' or '?' (for type-or-nil)
443448
444 (see `tests/styles/colon.lua`)
449 (see @{colon.lua})
445450
446451 ## Adding new Tags
447452
560565 files are all marked as `@module lib` then a single module `lib` is generated, containing all
561566 the docs from the separate files. For this, use `merge=true`.
562567
563 See 'tests/examples/mylib.c' for the full example.
568 See @{mylib.c} for the full example.
564569
565570 ## Basic Usage
566571
627632
628633 You can request the processor you like with `format = 'markdown|discount|lunamark'`, and
629634 LDoc will attempt to use it. If it can't find it, it will look for one of the other
630 markdown processors.
635 markdown processors; the original `markdown.lua` ships with LDoc, although it's slow
636 for larger documents.
631637
632638 Even with the default of 'plain' some minimal processing takes place, in particular empty lines
633 are treated as line breaks.
639 are treated as line breaks. If 'process_backticks=true` then backticks will be
640 expanded into documentation links like `@{\ref}` and converted into `<code>ref</code>`
641 otherwise.
634642
635643 This formatting applies to all of a project, including any readmes and so forth. You may want
636644 Markdown for this 'narrative' documentation, but not for your code comments. `plain=true` will
842850 resolves to 'examples/testu.lua.html'.
843851
844852 Examples may link back to the API documentation, for instance the example `input.lua` has a
845 @\{spawn_process} inline reference.
853 `@{\spawn_process}` inline reference.
846854
847855 By default, LDoc uses a built-in Lua code 'prettifier'. See-references are allowed in comments,
848856 and also in code if they're enclosed in backticks.
860868 This goes under the 'Topics' global section; the 'Contents' of this document is generated
861869 from the second-level (##) headings of the readme.
862870
863 Readme files are always processed with the current Markdown processor, but may also contain @\{} references back
871 Readme files are always processed with the current Markdown processor, but may also contain `@{\ref}` references back
864872 to the documentation and to example files. Any symbols within backticks will be expanded as
865873 references, if possible. As with doc comments, a link to a standard Lua function like
866 @\{os.execute} will work as well. Any code sections will be pretty-printed as Lua, unless
874 `@{\os.execute}` will work as well. Any code sections will be pretty-printed as Lua, unless
867875 the first indented line is '@plain'. (See the source for this readme to see how it's used.)
868876
869877 Another name for `readme` is `topics`, which is more descriptive. From LDoc 1.2,
877885 that the first heading must be top-level relative to the headings that follow, and must
878886 start at the first line.
879887
880 A reference like @\{string.upper} is unambiguous, and will refer to the online Lua manual.
888 A reference like `@{\string.upper}` is unambiguous, and will refer to the online Lua manual.
881889 In a project like Penlight, it can get tedious to have to write out fully qualified names
882 like @\{pl.utils.printf}. The first simplification is to use the `package` field to resolve
890 like `@{\pl.utils.printf}`. The first simplification is to use the `package` field to resolve
883891 unknown references, which in this case is 'pl'. (Previously we discussed how `package` is
884892 used to tell LDoc where the base package is in cases where the module author wishes to
885893 remain vague, but it does double-duty here.) A further level of simplification comes from
886 the @lookup directive in documents, which must start at the first column on its own line.
887 For instance, if I am talking about `pl.utils`, then I can say "@lookup utils" and
888 thereafter references like @\{printf} will resolve correctly.
894 the `@lookup` directive in documents, which must start at the first column on its own line.
895 For instance, if I am talking about `pl.utils`, then I can say `@lookup utils` and
896 thereafter references like `@{\printf}` will resolve correctly.
889897
890898 If you look at the source for this document, you will see a `@lookup doc.md` which allows
891 direct references to sections like @{Readme_files|this}.
899 direct references to sections like @{Readme_files|this} with `@{\Readme_files|this}`.
892900
893901 Remember that the default is for references in backticks to be resolved; unlike @
894902 references, it is not an error if the reference cannot be found.
895903
896904 The _sections_ of a document (the second-level headings) are also references. This
897 particular section can be refered to as @\{doc.md.Resolving_References_in_Documents} - the
905 particular section can be refered to as `@{\doc.md.Resolving_References_in_Documents}` - the
898906 rule is that any non-alphabetic character is replaced by an underscore.
899907
900
901908 ## Tag Modifiers
902909
903910 Ay tag may have _tag modifiers_. For instance, you may say
904 @\param[type=number] and this associates the modifier `type` with value `number` with this
905 particular param tag. A shorthand can be introduced for this common case, which is "@tparam
906 <type> <parmname> <comment>"; in the same way @\treturn is defined.
911 `@param[type=number]` and this associates the modifier `type` with value `number` with this
912 particular param tag. A shorthand has been introduced for this common case, which is `@tparam
913 <type> <parmname> <comment>`; in the same way `@treturn` is defined.
907914
908915 This is useful for larger projects where you want to provide the argument and return value
909 types for your API, in a structured way that can be easily extracted later. There is a
910 useful function for creating new tags that can be used in `config.ld`:
916 types for your API, in a structured way that can be easily extracted later.
917
918 These types can be combined, so that "?string|number" means "ether a string or a number";
919 "?string" is short for "?|nil|string". However, for this last case you should usually use the
920 `opt` modifier discussed below.
921
922 There is a useful function for creating new tags that can be used in `config.ld`:
911923
912924 tparam_alias('string','string')
913925
914 That is, "@string" will now have the same meaning as "@tparam string".
926 That is, "@string" will now have the same meaning as "@tparam string"; this also applies
927 to the optional type syntax "?|T1|T2".
915928
916929 From 1.3, the following standard type aliases are predefined:
917930
923936 * `tab` 'table'
924937 * `thread`
925938
926 The exact form of `<type>` is not defined, but here is a suggested scheme:
927
928 number -- a plain type
929 Bonzo -- a known type; a reference link will be generated
930 {string,number} -- a 'list' tuple, built from type expressions
931 {A=string,N=number} -- a 'struct' tuple, ditto
932 {Bonzo,...} -- an array of Bonzo objects
933 {[string]=Bonzo,...} -- a map of Bonzo objects with string keys
934 Array(Bonzo) -- (assuming that Array is a container)
935
936 Currently the `type` modifier is the only one known and used by LDoc when generating HTML
937 output. However, any other modifiers are allowed and are available for use with your own
938 templates or for extraction by your own tools.
939 When using 'colon-style' (@{colon.lua}) it's possible to directly use types by prepending
940 them with '!'; '?' is also naturally understood.
941
942 The exact form of `<type>` is not defined, but here is one suggested scheme:
943
944 * `number` -- a plain type
945 * `Bonzo` -- a known type; a reference link will be generated
946 * `{string,number}` -- a 'list' tuple of two values, built from type expressions
947 * `{A=string,N=number}` -- a 'struct', ditto (But it's often better to create a named table and refer to it)
948 * `{Bonzo,...}` -- an array of Bonzo objects
949 * `{[string]=Bonzo,...}` -- a map of Bonzo objects with string keys
950 * `Array(Bonzo)` -- (assuming that Array is a container type)
939951
940952 The `alias` function within configuration files has been extended so that alias tags can be
941953 defined as a tag plus a set of modifiers. So `tparam` is defined as:
957969 end
958970 ----> displayed as: two (one [, two], three [, four])
959971
960 This modifier can also be used with type aliases. If a value is given for the modifier
972 This modifier can also be used with type aliases. If a value is given for `opt`
961973 then LDoc can present this as the default value for this optional argument.
962974
963975 --- a function with typed args.
972984 end
973985 ----> displayed as: one (name, age [, calender='gregorian' [, offset=0]])
974986
975 (See `tests/styles/four.lua`)
987 Currently the `type` and `opt` modifiers are the only ones known and used by LDoc when generating HTML
988 output. However, any other modifiers are allowed and are available for use with your own
989 templates or for extraction by your own tools.
990
991 (See @{four.lua})
976992
977993 ## Fields allowed in `config.ld`
978994
979 These mostly have the same meaning as the corresponding parameters:
995 _Same meaning as the corresponding parameters:_
980996
981997 - `file` a file or directory containing sources. In `config.ld` this can also be a table
982998 of files and directories.
9951011 template. In `config.ld` they may also be `true`, meaning use the same directory as the
9961012 configuration file.
9971013 - `merge` allow documentation from different files to be merged into modules without
998 explicit @submodule tag
999
1000 These only appear in `config.ld`:
1001
1002 - `description` a project description used under the project title
1014 explicit @submodule tag
1015
1016 _These only appear in config.ld:_
1017
1018 - `description` a short project description used under the project title
1019 - `full_description` when you _really_ need a longer project description
10031020 - `examples` a directory or file: can be a table
10041021 - `readme` or `topics` readme files (to be processed with Markdown)
10051022 - `pretty` code prettify 'lua' (default) or 'lxsh'
10061023 - `charset` use if you want to override the UTF-8 default (also @charset in files)
1024 - `sort` set if you want all items in alphabetical order
10071025 - `no_return_or_parms` don't show parameters or return values in output
1008 - `backtick_references` whether references in backticks will be resolved
1026 - `backtick_references` whether references in backticks will be resolved. Happens by default
1027 when using Markdown. When explicit will expand non-references in backticks into `<code>` elements
10091028 - `plain` set to true if `format` is set but you don't want code comments processed
10101029 - `wrap` ??
10111030 - `manual_url` point to an alternative or local location for the Lua manual, e.g.
10131032 - `no_summary` suppress the Contents summary
10141033 - `custom_see_handler` function that filters see-references
10151034 - `not_luadoc` set to `true` if the docs break LuaDoc compatibility
1016
1017 Available functions are:
1035 - `no_space_before_args` set to `true` if you do not want a space between a function's name and its arguments.
1036 - `template_escape` overrides the usual '#' used for Lua code in templates. This needs to be changed if the output format is Markdown, for instance.
1037
1038 _Available functions are:_
10181039
10191040 - `alias(a,tag)` provide an alias `a` for the tag `tag`, for instance `p` as short for
10201041 `param`
10231044 - `add_section`
10241045 - `new_type(tag,header,project_level)` used to add new tags, which are put in their own
10251046 section `header`. They may be 'project level'.
1026 - `tparam_alias(name,type)` for instance, you may wish that `Object` means `@\tparam
1027 Object`.
1047 - `tparam_alias(name,type)` for instance, you may wish that `Object` becomes a new tag alias
1048 that means `@tparam Object`.
10281049 - `custom_see_handler(pattern,handler)`. If a reference matches `pattern`, then the
10291050 extracted values will be passed to `handler`. It is expected to return link text
10301051 and a suitable URI. (This match will happen before default processing.)
10581079
10591080 ## Generating HTML
10601081
1061 LDoc, like LuaDoc, generates output HTML using a template, in this case `ldoc_ltp.lua`. This
1082 LDoc, like LuaDoc, generates output HTML using a template, in this case `ldoc/html/ldoc_ltp.lua`. This
10621083 is expanded by the powerful but simple preprocessor devised originally by [Rici
1084 Lake](http://lua-users.org/wiki/SlightlyLessSimpleLuaPreprocessor) which is now part of
10631085 Lake](http://lua-users.org/wiki/SlightlyLessSimpleLuaPreprocessor) which is now part of
10641086 Penlight. There are two rules - any line starting with '#' is Lua code, which can also be
10651087 embedded with '$(...)'.
10911113 extension to use; this can also be set in the configuration file. So it's possible to write
10921114 a template that converts LDoc output to LaTex, for instance. The separation of processing
10931115 and presentation makes this kind of new application possible with LDoc.
1116
1117 From 1.4, LDoc has some limited support for generating Markdown output, although only
1118 for single files currently. Use `--ext md` for this. 'ldoc/html/ldoc_mdtp.lua' defines
1119 the template for Markdown.
10941120
10951121 ## Internal Data Representation
10961122
00 --- creating and controlling coroutines.
1 -- @module coroutine
12
2 module 'coroutine'
3 local coroutine = {}
34
45 ---
56 -- Creates a new coroutine, with body `f`. `f` must be a Lua
4546 -- `yield` are passed as extra results to `resume`.
4647 function coroutine.yield(...) end
4748
49 return coroutine
00 --- getting runtime debug information.
1 -- @module debug
12
2 module 'debug'
3
3 local debug = {}
44 ---
55 -- Enters an interactive mode with the user, running each string that
66 -- the user enters. Using simple commands and other debug facilities,
120120 -- with the given index. Otherwise, it returns the name of the upvalue.
121121 function debug.setupvalue(func, up, value) end
122122
123 return debug
7272 globals.set_manual_url 'http://www.lua.org/manual/5.1/manual.html'
7373 end
7474
75 -- external libs tracked by LDoc using LDoc style
76 local xlibs = {
77 lfs='lfs.html', lpeg='lpeg.html',
78 }
79 local xlib_url = 'http://stevedonovan.github.io/lua-stdlibs/modules/'
80
7581 local tables = globals.tables
7682
77 local function function_ref (name)
78 return {href = fun_ref..name, label = name}
83 local function function_ref (name,tbl)
84 local href
85 if not tbl then -- can only be a standard Lua global function
86 if globals.functions[name] then
87 return {href = fun_ref..name, label = name}
88 else
89 return nil
90 end
91 end
92 if tables[tbl] then -- function inside standard Lua table
93 local t = rawget(_G,tbl) -- do a quick sanity check
94 if not rawget(t,name) then
95 return nil
96 end
97 name = tbl..'.'..name
98 href = fun_ref..name
99 elseif xlibs[tbl] then -- in external libs, use LDoc style
100 local t = require('ldoc.builtin.'..tbl)
101 if not rawget(t,name) then
102 return nil
103 end
104 href = xlib_url..xlibs[tbl]..'#'..name
105 name = tbl..'.'..name
106 else
107 return nil
108 end
109 return {href = href, label = name}
79110 end
80111
81 local function module_ref (name)
82 return {href = manual..tables[name], label = name}
112 local function module_ref (tbl)
113 local href
114 if tables[tbl] ~= nil then -- standard Lua table
115 href = manual..tables[tbl]
116 elseif xlibs[tbl] then -- external lib
117 href = xlib_url..xlibs[tbl]
118 else
119 return nil
120 end
121 return {href = href, label = tbl}
83122 end
84123
85124 function globals.lua_manual_ref (name)
86125 local tbl,fname = tools.split_dotted_name(name)
126 local ref
87127 if not tbl then -- plain symbol
88 if functions[name] then
89 return function_ref(name)
90 end
91 if tables[name] then
92 return module_ref(name)
93 end
128 ref = function_ref(name)
129 if ref then return ref end
130 ref = module_ref(name)
131 if ref then return ref end
94132 else
95 if tables[tbl] then
96 return function_ref(name)
97 end
133 ref = function_ref(fname,tbl)
134 if ref then return ref end
98135 end
99136 return nil
100137 end
00 --- Reading and Writing Files.
1 -- @module io
12
2 module 'io'
3 local io = {}
34
45 ---
56 -- Equivalent to `file:close()`. Without a `file`, closes the default
154155 -- `string.format` before `write`.
155156 function file:write(...) end
156157
158 return io
00 --- File and Directory manipulation
1 -- @module lfs
12
2 module 'lfs'
3 local lfs = {}
34
45 ---
56 -- Returns a table with the file attributes corresponding to filepath (or nil
7273 -- and its length; both should be numbers.
7374 -- Returns true if the operation was successful; in case of error, it returns
7475 -- nil plus an error string.
75 function lfs.lock(filehandle, mode, start, length)
76 function lfs.lock(filehandle, mode, start, length) end
7677
7778 ---
7879 -- Creates a new directory. The argument is the name of the new directory.
119120 -- Returns true if the operation was successful; in case of error, it returns
120121 -- nil plus an error string.
121122 function lfs.unlock(filehandle, start, length) end
123
124 return lfs
00 --- LPeg PEG pattern matching.
1
2 module 'lpeg'
1 -- @module lpeg
2
3 local lpeg = {}
34
45 ---
56 -- The matching function. It attempts to match the given pattern against the
208209 -- Any extra values returned by the function become the values produced by the
209210 -- capture.
210211 function lpeg.Cmt(patt, function) end
212
213 return lpeg
00 --- standard mathematical functions.
1 -- @module math
12
2 module 'math'
3 local math = {}
34
45 ---
56 -- Returns the absolute value of `x`.
139140 -- Returns the hyperbolic tangent of `x`.
140141 function math.tanh(x) end
141142
143 return math
00 --- Operating System facilities like date, time and program execution.
1 -- @module os
12
2 module 'os'
3 local os = {}
34
45 ---
56 -- Returns an approximation of the amount in seconds of CPU time used by
107108 -- removes the file when the program ends.
108109 function os.tmpname() end
109110
111 return os
00 --- controlling how `require` finds packages.
1 -- @module package
12
2 module 'package'
3 local package = {}
34
45 ---
56 -- The path used by `require` to search for a C loader.
9293 -- environment. To be used as an option to function `module`.
9394 function package.seeall(module) end
9495
96 return package
00 --- string operations like searching and matching.
1 -- @module string
12
2 module 'string'
3 local string = {}
34
45 ---
56 -- Returns the internal numerical codes of the characters `s[i]`, `s[i+1]`,
169170 -- definition of what a lowercase letter is depends on the current locale.
170171 function string.upper(s) end
171172
173 return string
174
00 --- manipulating Lua tables.
1 -- @module table
12
2 module 'table'
3 local table = {}
34
45 ---
56 -- Given an array where all elements are strings or numbers, returns
3839 -- (so that `not comp(a[i+1],a[i])` will be true after the sort). If `comp`
3940 -- is not given, then the '<' operator will be used.
4041 function table.sort(table , comp) end
42
43 return table
2020 -- - 'N' tags which have no associated value, like 'local` (TAG_FLAG)
2121 -- - 'T' tags which represent a type, like 'function' (TAG_TYPE)
2222 local known_tags = {
23 param = 'M', see = 'M', usage = 'ML', ['return'] = 'M', field = 'M', author='M';
23 param = 'M', see = 'M', usage = 'ML', ['return'] = 'M', field = 'M', author='M',set='M';
2424 class = 'id', name = 'id', pragma = 'id', alias = 'id', within = 'id',
2525 copyright = 'S', summary = 'S', description = 'S', release = 'S', license = 'S',
2626 fixme = 'S', todo = 'S', warning = 'S', raise = 'S', charset = 'S',
2727 ['local'] = 'N', export = 'N', private = 'N', constructor = 'N', static = 'N';
2828 -- project-level
29 module = 'T', script = 'T', example = 'T', topic = 'T', submodule='T',
29 module = 'T', script = 'T', example = 'T', topic = 'T', submodule='T', classmod='T',
3030 -- module-level
3131 ['function'] = 'T', lfunction = 'T', table = 'T', section = 'T', type = 'T',
3232 annotation = 'T', factory = 'T';
3838 script = true,
3939 example = true,
4040 topic = true,
41 submodule = true;
41 submodule = true,
42 classmod = true,
4243 }
4344
4445 known_tags._code_types = {
4546 module = true,
46 script = true
47 script = true,
48 classmod = true,
49 }
50
51 known_tags._presentation_names = {
52 classmod = 'Class',
4753 }
4854
4955 known_tags._module_info = {
98104 return tag == 'type' or tag == 'factory'
99105 end
100106
107 -- how the type wants to be formally presented; e.g. 'module' becomes 'Module'
108 -- but 'classmod' will become 'Class'
109 function doc.presentation_name (tag)
110 local name = known_tags._presentation_names[tag]
111 if not name then
112 name = tag:gsub('(%a)(%a*)',function(f,r)
113 return f:upper()..r
114 end)
115 end
116 return name
117 end
118
101119 function doc.module_info_tags ()
102120 return List.iter(known_tags._module_info)
103121 end
104122
105123
106 -- annotation tags can appear anywhere in the code and may contain of these tags:
124 -- annotation tags can appear anywhere in the code and may contain any of these tags:
107125 known_tags._annotation_tags = {
108126 fixme = true, todo = true, warning = true
109127 }
176194 return this_mod and this_mod.section and this_mod.section.type
177195 end
178196
179 local function find_module_in_files (name)
197 function File:find_module_in_files (name)
180198 for f in File.list:iter() do
181199 for m in f.modules:iter() do
182200 if m.name == name then
215233 -- if name is 'package.mod', then mod_name is 'mod'
216234 package,mname = split_dotted_name(this_mod.name)
217235 if self.args.merge then
218 local mod,mf = find_module_in_files(item.name)
236 local mod,mf = self:find_module_in_files(item.name)
219237 if mod then
220238 print('found master module',mf)
221239 this_mod = mod
229247 elseif item.type == 'submodule' then
230248 local mf
231249 submodule = true
232 this_mod,mf = find_module_in_files(item.name)
250 this_mod,mf = self:find_module_in_files(item.name)
233251 if this_mod == nil then
234252 self:error("'"..item.name.."' not found for submodule")
235253 end
267285 -- add the item to the module's item list
268286 if this_mod then
269287 -- new-style modules will have qualified names like 'mod.foo'
270 --require 'pl.pretty'.dump(item.tags)
271288 local mod,fname = split_dotted_name(item.name)
272289 -- warning for inferred unqualified names in new style modules
273290 -- (retired until we handle methods like Set:unset() properly)
297314
298315 -- right, this item was within a section or a 'class'
299316 local section_description
300 if this_mod.section then
317 local classmod = this_mod.type == 'classmod'
318 if this_mod.section or classmod then
319 local stype
301320 local this_section = this_mod.section
302 item.section = this_section.display_name
321 if this_section then
322 item.section = this_section.display_name
323 stype = this_section.type
324 end
303325 -- if it was a class, then if the name is unqualified then it becomes
304326 -- 'Class:foo' (unless flagged as being a constructor, static or not a function)
305 local stype = this_section.type
306 if doc.class_tag(stype) then
327 if doc.class_tag(stype) or classmod then
307328 if not item.name:match '[:%.]' then -- not qualified
308 local class = this_section.name
329 local class = classmod and this_mod.name or this_section.name
330 local lang = this_mod.file.lang
309331 local static = item.tags.constructor or item.tags.static or item.type ~= 'function'
310 item.name = class..(not static and ':' or '.')..item.name
332 item.name = class..(not static and lang.method_call or '.')..item.name
311333 end
312334 if stype == 'factory' then
313335 if item.tags.private then to_be_removed = true
319341 end
320342 end
321343 end
322 section_description = this_section.summary..' '..(this_section.description or '')
344 if this_section then
345 section_description = this_section.summary..' '..(this_section.description or '')
346 this_section.summary = ''
347 elseif item.tags.within then
348 section_description = item.tags.within
349 item.section = section_description
350 else
351 section_description = "Methods"
352 item.section = item.type
353 end
323354 elseif item.tags.within then
324355 section_description = item.tags.within
325356 item.section = section_description
390421
391422 function Item:trailing_warning (kind,tag,rest)
392423 if type(rest)=='string' and #rest > 0 then
393 Item.warning(self,kind.." tag: '"..tag..'" has trailing text; use no_luadoc=true\n'..rest)
424 Item.warning(self,kind.." tag: '"..tag..'" has trailing text; use not_luadoc=true if you want description to continue between tags\n'..rest)
394425 end
395426 end
396427
523554 self.type = read_del(tags,'class')
524555 self.modifiers = extract_tag_modifiers(tags)
525556 self.usage = read_del(tags,'usage')
526 -- see tags are multiple, but they may also be comma-separated
557 tags.see = read_del(tags,'see')
527558 if tags.see then
528 tags.see = tools.expand_comma_list(read_del(tags,'see'))
559 tags.see = tools.identifier_list(tags.see)
529560 end
530561 if doc.project_level(self.type) then
531562 -- we are a module, so become one!
628659 local names = List()
629660 self.subparams = {}
630661 for i,name in ipairs(original_names) do
662 if type(name) ~= 'string' then
663 self:error("declared table cannot have array entries")
664 end
631665 local pname,field = split_iden(name)
632666 if field then
633667 if not fields then
705739 end
706740 opt = m.optchain or m.opt
707741 if opt then
708 acc(' [')
742 acc('[')
709743 npending=npending+1
710744 end
711745 end
717751 return '('..table.concat(buffer)..')'
718752 end
719753
720 function Item:type_of_param(p)
754 function Item:param_modifiers (p)
721755 local mods = self.modifiers[self.parameter]
722756 if not mods then return '' end
723 local mparam = rawget(mods,p)
757 return rawget(mods,p)
758 end
759
760 function Item:type_of_param(p)
761 local mparam = self:param_modifiers(p)
724762 return mparam and mparam.type or ''
763 end
764
765 function Item:default_of_param(p)
766 local m = self:param_modifiers(p)
767 if not m then return nil end
768 local opt = m.optchain or m.opt
769 if opt == true then return nil end
770 return opt
725771 end
726772
727773 function Item:type_of_ret(idx)
798844 return {mod = mod_ref, name = name, label=s}
799845 end
800846
801 function Module:process_see_reference (s,modules)
847 function Module:process_see_reference (s,modules,istype)
802848 local mod_ref,fun_ref,name,packmod
803849 local ref = custom_see_references(s)
804850 if ref then return ref end
805851 if not s:match '^[%w_%.%:%-]+$' or not s:match '[%w_]$' then
806852 return nil, "malformed see reference: '"..s..'"'
807853 end
854 local function ismod(item)
855 if item == nil then return false end
856 if not istype then return true
857 else
858 return item.type == 'classmod'
859 end
860 end
808861 -- is this a fully qualified module name?
809862 local mod_ref = modules.by_name[s]
810 if mod_ref then return reference(s, mod_ref,nil) end
863 if ismod(mod_ref) then return reference(s, mod_ref,nil) end
811864 -- module reference?
812865 mod_ref = self:hunt_for_reference(s, modules)
813 if mod_ref then return mod_ref end
866 if ismod(mod_ref) then return mod_ref end
814867 -- method reference? (These are of form CLASS.NAME)
815868 fun_ref = self.items.by_name[s]
816869 if fun_ref then return reference(s,self,fun_ref) end
839892 end
840893 else -- plain jane name; module in this package, function in this module
841894 mod_ref = modules.by_name[self.package..'.'..s]
842 if mod_ref then return reference(s, mod_ref,nil) end
895 if ismod(mod_ref) then return reference(s, mod_ref,nil) end
843896 fun_ref = self.items.by_name[s]
844897 if fun_ref then return reference(s, self,fun_ref)
845898 else
916969 end
917970
918971 function Module:dump(verbose)
919 if self.type ~= 'module' then return end
972 if not doc.project_level(self.type) then return end
920973 print '----'
921974 print(self.type..':',self.name,self.summary)
922975 if self.description then print(self.description) end
8484 <div id="content">
8585
8686 #if module then
87 <h1>$(ldoc.titlecase(module.type)) <code>$(module.name)</code></h1>
87 <h1>$(ldoc.module_typename(module)) <code>$(module.name)</code></h1>
8888 # end
8989
9090 # if ldoc.body then -- verbatim HTML as contents; 'non-code' entries
105105 <h3>Info:</h3>
106106 <ul>
107107 # for tag, value in ldoc.pairs(module.info) do
108 <li><strong>$(tag)</strong>: $(value)</li>
108 <li><strong>$(tag)</strong>: $(M(value,module))</li>
109109 # end
110110 </ul>
111111 # end -- if module.info
164164 <ul>
165165 # end
166166 # for p in iter(param) do
167 # local name,tp = item:display_name_of(p), ldoc.typename(item:type_of_param(p))
167 # local name,tp,def = item:display_name_of(p), ldoc.typename(item:type_of_param(p)), item:default_of_param(p)
168168 <li><span class="parameter">$(name)</span>
169169 # if tp ~= '' then
170170 <span class="types">$(tp)</span>
171 # end
172 $(M(item.params[p],item))</li>
171 # end
172 $(M(item.params[p],item))
173 # if def then
174 (<em>default</em> $(def))
175 # end
176 </li>
173177 # end
174178 # if sublist then
175179 </li></ul>
200204
201205 # if item.see then
202206 # local li,il = use_li(item.see)
203 <h3>see also:</h3>
207 <h3>See also:</h3>
204208 <ul>
205209 # for see in iter(item.see) do
206210 $(li)<a href="$(ldoc.href(see))">$(see.label)</a>$(il)
249253 </div> <!-- id="content" -->
250254 </div> <!-- id="main" -->
251255 <div id="about">
252 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.3.12</a></i>
256 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.0</a></i>
253257 </div> <!-- id="about" -->
254258 </div> <!-- id="container" -->
255259 </body>
0 return [[
1 > local lev = ldoc.level or 2
2 > local lev1,lev2 = ('#'):rep(lev),('#'):rep(lev+1)
3 > for kind, items in module.kinds() do
4 > local kitem = module.kinds:get_item(kind)
5 > if kitem then
6 $(lev1) $(ldoc.descript(kitem))
7
8 > end
9 > for item in items() do
10 $(lev2) $(ldoc.display_name(item))
11
12 $(ldoc.descript(item))
13
14 > end
15 > end
16 ]]
1717 local path = require 'pl.path'
1818 local stringx = require 'pl.stringx'
1919 local template = require 'pl.template'
20 local tablex = require 'pl.tablex'
2021 local tools = require 'ldoc.tools'
2122 local markup = require 'ldoc.markup'
2223 local prettify = require 'ldoc.prettify'
5455
5556 function html.generate_output(ldoc, args, project)
5657 local check_directory, check_file, writefile = tools.check_directory, tools.check_file, tools.writefile
58 local original_ldoc
59
60 local function save_and_set_ldoc (set)
61 if not set then return end
62 if not original_ldoc then
63 original_ldoc = tablex.copy(ldoc)
64 end
65 for s in set:iter() do
66 local var,val = s:match('([^=]+)=(.+)')
67 local num = tonumber(val)
68 if num then val = num
69 elseif val == 'true' then val = true
70 elseif val == 'false' then val = false
71 end
72 print('setting',var,val)
73 ldoc[var] = val
74 end
75 end
76
77 local function restore_ldoc ()
78 if original_ldoc then
79 ldoc = original_ldoc
80 end
81 end
5782
5883 function ldoc.escape(str)
5984 return (str:gsub("['&<>\"]", escape_table))
117142
118143 function ldoc.display_name(item)
119144 local name = item.display_name or item.name
120 if item.type == 'function' or item.type == 'lfunction' then return name..'&nbsp;'..item.args
121 else return name end
145 if item.type == 'function' or item.type == 'lfunction' then
146 if not ldoc.no_space_before_args then
147 name = name..' '
148 end
149 return name..item.args
150 else
151 return name
152 end
122153 end
123154
124155 function ldoc.no_spaces(s)
126157 return (s:gsub('%W','_'))
127158 end
128159
129 function ldoc.titlecase(s)
130 return (s:gsub('(%a)(%a*)',function(f,r)
131 return f:upper()..r
132 end))
160 function ldoc.module_typename(m)
161 return doc.presentation_name(m.type)
133162 end
134163
135164 function ldoc.is_list (t)
150179 end
151180 local types = {}
152181 for name in tp:gmatch("[^|]+") do
153 local ref,err = markup.process_reference(name)
182 local ref,err = markup.process_reference(name,true)
154183 if ref then
155184 types[#types+1] = ('<a class="type" href="%s">%s</a>'):format(ldoc.href(ref),ref.label or name)
156185 else
185214 ldoc.pairs = pairs
186215 ldoc.print = print
187216
217 -- Bang out the index.
188218 -- in single mode there is one module and the 'index' is the
189219 -- documentation for that module.
190220 ldoc.module = ldoc.single
195225 ldoc.root = true
196226 if ldoc.module then
197227 ldoc.module.info = get_module_info(ldoc.module)
228 ldoc.module.ldoc = ldoc
229 save_and_set_ldoc(ldoc.module.tags.set)
198230 end
199231 set_charset(ldoc)
200232 local out,err = template.substitute(module_template,{
201233 ldoc = ldoc,
202234 module = ldoc.module,
235 _escape = ldoc.template_escape
203236 })
204237 ldoc.root = false
205238 if not out then quit("template failed: "..err) end
239 restore_ldoc()
206240
207241 check_directory(args.dir) -- make sure output directory is ok
208242
209243 args.dir = args.dir .. path.sep
210244
211 check_file(args.dir..css, path.join(args.style,css)) -- has CSS been copied?
245 if css then -- has CSS been copied?
246 check_file(args.dir..css, path.join(args.style,css))
247 end
212248
213249 -- write out the module index
214250 out = cleanup_whitespaces(out)
215251 writefile(args.dir..args.output..args.ext,out)
216252
217253 -- in single mode, we exclude any modules since the module has been done;
218 -- this step is then only for putting out any examples or topics
254 -- ext step is then only for putting out any examples or topics
219255 local mods = List()
220256 for kind, modules in project() do
221257 local lkind = kind:lower()
227263 -- write out the per-module documentation
228264 -- note that we reset the internal ordering of the 'kinds' so that
229265 -- e.g. when reading a topic the other Topics will be listed first.
230 ldoc.css = '../'..css
266 if css then
267 ldoc.css = '../'..css
268 end
231269 for m in mods:iter() do
232270 local kind, lkind, modules = unpack(m)
233271 check_directory(args.dir..lkind)
235273 for m in modules() do
236274 ldoc.module = m
237275 ldoc.body = m.body
276 m.ldoc = ldoc
277 if m.tags.set then
278 save_and_set_ldoc(m.tags.set)
279 end
238280 set_charset(ldoc)
239281 m.info = get_module_info(m)
240282 if ldoc.body and m.postprocess then
242284 end
243285 out,err = template.substitute(module_template,{
244286 module=m,
245 ldoc = ldoc
287 ldoc = ldoc,
288 _escape = ldoc.template_escape
246289 })
247290 if not out then
248291 quit('template failed for '..m.name..': '..err)
250293 out = cleanup_whitespaces(out)
251294 writefile(args.dir..lkind..'/'..m.name..args.ext,out)
252295 end
296 restore_ldoc()
253297 end
254298 end
255299 if not args.quiet then print('output written to '..tools.abspath(args.dir)) end
44
55 local class = require 'pl.class'
66 local utils = require 'pl.utils'
7 local List = require 'pl.List'
78 local tools = require 'ldoc.tools'
89 local lexer = require 'ldoc.lexer'
910 local quit = utils.quit
7374 self.start_comment_ = '^%-%-%-+' -- used for doc comment line start
7475 self.block_comment = '^%-%-%[=*%[%-+' -- used for block doc comments
7576 self.end_comment_ = '[^%-]%-%-+\n$' ---- exclude --- this kind of comment ---
77 self.method_call = ':'
7678 self:finalize()
7779 end
7880
238240
239241
240242 -- note a difference here: we scan C/C++ code in full-text mode, not line by line.
241 -- This is because we can't detect multiline comments in line mode
243 -- This is because we can't detect multiline comments in line mode.
244 -- Note: this applies to C/C++ code used to generate _Lua_ documentation!
242245
243246 local CC = class(Lang)
244247
246249 self.line_comment = '^//+'
247250 self.start_comment_ = '^///+'
248251 self.block_comment = '^/%*%*+'
252 self.method_call = ':'
249253 self:finalize()
250254 end
251255
261265 return 'comment',v:sub(1,-3)
262266 end
263267
264 return { lua = Lua(), cc = CC() }
268 local Moon = class(Lua)
269
270 function Moon:_init()
271 self.line_comment = '^%-%-+' -- used for stripping
272 self.start_comment_ = '^%s*%-%-%-+' -- used for doc comment line start
273 self.block_comment = '^%-%-%[=*%[%-+' -- used for block doc comments
274 self.end_comment_ = '[^%-]%-%-+\n$' ---- exclude --- this kind of comment ---
275 self.method_call = '.'
276 self:finalize()
277 end
278
279 function Moon:item_follows (t,v,tok)
280 if t == '.' then -- enclosed in with statement
281 t,v = tnext(tok)
282 end
283 if t == 'iden' then
284 local name,t,v = tools.get_fun_name(tok,v,'')
285 if name == 'class' then
286 name,t,v = tools.get_fun_name(tok,v,'')
287 -- class!
288 return function(tags,tok)
289 tags:add('class','type')
290 tags:add('name',name)
291 end
292 elseif t == '=' or t == ':' then -- function/method
293 t,v = tnext(tok)
294 return function(tags,tok)
295 if not tags.name then
296 tags:add('name',name)
297 end
298 if t == '(' then
299 tags.formal_args,t,v = tools.get_parameters(tok)
300 else
301 tags.formal_args = List()
302 end
303 tags:add('class','function')
304 if t == '=' then
305 tags.formal_args:insert(1,'self')
306 tags.formal_args.comments = {self=''}
307 end
308 end
309 else
310 return nil
311 end
312 end
313 end
314
315 return { lua = Lua(), cc = CC(), moon = Moon() }
117117
118118
119119 -- Set up a table for holding local functions to avoid polluting the global namespace
120 -- Penlight 1.2 defines compatible 5.1 setfenv in utils table
120121 local M = {}
121122 local MT = {__index = _G}
122123 setmetatable(M, MT)
123 setfenv(1, M)
124124
125125 ----------------------------------------------------------------------
126126 -- Utility functions
11331133 -- End of module
11341134 ----------------------------------------------------------------------
11351135
1136 setfenv(1, _G)
11371136 M.lock(M)
11381137
11391138 -- Expose markdown function to the world
1414 -- inline <references> use same lookup as @see
1515 local function resolve_inline_references (ldoc, txt, item, plain)
1616 local res = (txt:gsub('@{([^}]-)}',function (name)
17 if name:match '^\\' then return '@{'..name:sub(2)..'}' end
1718 local qname,label = utils.splitv(name,'%s*|')
1819 if not qname then
1920 qname = name
4445 if ref then
4546 return ('<a href="%s">%s</a> '):format(ldoc.href(ref),name)
4647 else
47 return '`'..name..'`'
48 return '<code>'..name..'</code>'
4849 end
4950 end)
5051 end
280281 function markup.create (ldoc, format, pretty)
281282 local processor
282283 markup.plain = true
284 if format == 'backtick' then
285 ldoc.backtick_references = true
286 format = 'plain'
287 end
283288 backtick_references = ldoc.backtick_references
284289 global_context = ldoc.package and ldoc.package .. '.'
285290 prettify.set_prettifier(pretty)
286291
287 markup.process_reference = function(name)
292 markup.process_reference = function(name,istype)
288293 if local_context == 'none.' and not name:match '%.' then
289294 return nil,'not found'
290295 end
291296 local mod = ldoc.single or ldoc.module or ldoc.modules[1]
292 local ref,err = mod:process_see_reference(name, ldoc.modules)
297 local ref,err = mod:process_see_reference(name, ldoc.modules, istype)
293298 if ref then return ref end
294299 if global_context then
295300 local qname = global_context .. name
296 ref = mod:process_see_reference(qname, ldoc.modules)
301 ref = mod:process_see_reference(qname, ldoc.modules, istype)
297302 if ref then return ref end
298303 end
299304 if local_context then
300305 local qname = local_context .. name
301 ref = mod:process_see_reference(qname, ldoc.modules)
306 ref = mod:process_see_reference(qname, ldoc.modules, istype)
302307 if ref then return ref end
303308 end
304309 -- note that we'll return the original error!
7373 local Tags = {}
7474 Tags.__index = Tags
7575
76 function Tags.new (t)
76 function Tags.new (t,name)
77 local class
78 if name then
79 class = t
80 t = {}
81 end
7782 t._order = List()
78 return setmetatable(t,Tags)
83 local tags = setmetatable(t,Tags)
84 if name then
85 tags:add('class',class)
86 tags:add('name',name)
87 end
88 return tags
7989 end
8090
8191 function Tags:add (tag,value)
153163 local current_item, module_item
154164
155165 F.args = args
156
166 F.lang = lang
157167 F.base = package
158168
159169 local tok,f = lang.lexer(fname)
160170 if not tok then return nil end
161171
162 local function lineno ()
172 local function lineno ()
163173 return tok:lineno()
164 end
174 end
165175
166176 local function filename () return fname end
167177
228238
229239 if lang:empty_comment(v) then -- ignore rest of empty start comments
230240 t,v = tok()
241 if t == 'space' and not v:match '\n' then
242 t,v = tok()
243 end
231244 end
232245
233246 while t and t == 'comment' do
343356 if module_item then
344357 F:error("Module already declared!")
345358 end
359 if tags.class == 'classmod' then
360 tags = tags.new('section','methods')
361 tags:add('summary','Methods')
362 F:new_item(tags,line)
363 end
346364 module_item = current_item
347365 end
348366 end
1717
1818 -- this constructs an iterator over a list of objects which returns only
1919 -- those objects where a field has a certain value. It's used to iterate
20 -- only over functions or tables, etc.
20 -- only over functions or tables, etc. If the list of item has a module
21 -- with a context, then use that to pre-sort the fltered items.
2122 -- (something rather similar exists in LuaDoc)
2223 function M.type_iterator (list,field,value)
2324 return function()
24 local i = 1
25 return function()
26 local val = list[i]
27 while val and val[field] ~= value do
28 i = i + 1
29 val = list[i]
30 end
31 i = i + 1
32 if val then return val end
33 end
25 local fls = list:filter(function(item)
26 return item[field] == value
27 end)
28 local mod = fls[1] and fls[1].module
29 local ldoc = mod and mod.ldoc
30 if ldoc and ldoc.sort then
31 fls:sort(function(ia,ib)
32 return ia.name < ib.name
33 end)
34 end
35 return fls:iter()
3436 end
3537 end
3638
150152 end
151153 end
152154
153 -- expand lists of possibly qualified identifiers
154 -- given something like {'one , two.2','three.drei.drie)'}
155 -- it will output {"one","two.2","three.drei.drie"}
156 function M.expand_comma_list (ls)
157 local new_ls = List()
158 for s in ls:iter() do
159 s = s:gsub('[^%.:%-%w_]*$','')
160 if s:find ',' then
161 new_ls:extend(List.split(s,'%s*,%s*'))
162 else
163 new_ls:append(s)
164 end
165 end
166 return new_ls
167 end
168
169155 -- grab lines from a line iterator `iter` until the line matches the pattern.
170156 -- Returns the joined lines and the line, which may be nil if we run out of
171157 -- lines.
183169
184170 function M.extract_identifier (value)
185171 return value:match('([%.:%-_%w]+)(.*)$')
172 end
173
174 function M.identifier_list (ls)
175 local ns = List()
176 if type(ls) == 'string' then ls = List{ns} end
177 for s in ls:iter() do
178 if s:match ',' then
179 ns:extend(List.split(s,'[,%s]+'))
180 else
181 ns:append(s)
182 end
183 end
184 return ns
186185 end
187186
188187 function M.strip (s)
288287 tok = M.space_skip_getter(tok)
289288 local args = List()
290289 args.comments = {}
291 local ltl = lexer.get_separated_list(tok,endtoken,delim)
290 local ltl,tt = lexer.get_separated_list(tok,endtoken,delim)
292291
293292 if not ltl or not ltl[1] or #ltl[1] == 0 then return args end -- no arguments
294293
343342 end
344343 end
345344
346 ----[[
347345 -- we had argument comments
348346 -- but the last one may be outside the parens! (Geoff style)
349347 -- (only try this stunt if it's a function parameter list!)
352350 local last_arg = args[n]
353351 if not args.comments[last_arg] then
354352 while true do
355 local t = {tok()}
356 if type_of(t) == 'comment' then
357 set_comment(n,t)
353 tt = {tok()}
354 if type_of(tt) == 'comment' then
355 set_comment(n,tt)
358356 else
359357 break
360358 end
361359 end
362360 end
363361 end
364 --]]
365 return args
366 end
367
368 -- parse a Lua identifier - contains names separated by . and :.
369 function M.get_fun_name (tok,first)
362 -- return what token we ended on as well - can be token _past_ ')'
363 return args,tt[1],tt[2]
364 end
365
366 -- parse a Lua identifier - contains names separated by . and (optionally) :.
367 -- Set `colon` to be the secondary separator, '' for none.
368 function M.get_fun_name (tok,first,colon)
370369 local res = {}
371370 local t,name,sep
371 colon = colon or ':'
372372 if not first then
373373 t,name = tnext(tok)
374374 else
376376 end
377377 if t ~= 'iden' then return nil end
378378 t,sep = tnext(tok)
379 while sep == '.' or sep == ':' do
379 while sep == '.' or sep == colon do
380380 append(res,name)
381381 append(res,sep)
382382 t,name = tnext(tok)
432432
433433 function M.process_file_list (list, mask, operation, ...)
434434 local exclude_list = list.exclude and M.files_from_list(list.exclude, mask)
435 local function process (f,...)
435 local files = List()
436 local function process (f)
436437 f = M.abspath(f)
437438 if not exclude_list or exclude_list and exclude_list:index(f) == nil then
438 operation(f, ...)
439 files:append(f)
439440 end
440441 end
441442 for _,f in ipairs(list) do
442443 if path.isdir(f) then
443 local files = List(dir.getallfiles(f,mask))
444 for f in files:iter() do
445 process(f,...)
444 local dfiles = List(dir.getallfiles(f,mask))
445 for f in dfiles:iter() do
446 process(f)
446447 end
447448 elseif path.isfile(f) then
448 process(f,...)
449 process(f)
449450 else
450451 quit("file or directory does not exist: "..M.quote(f))
451452 end
453 end
454
455 if list.sortfn then
456 files:sort(list.sortfn)
457 end
458
459 for f in files:iter() do
460 operation(f,...)
452461 end
453462 end
454463
3434
3535 --- @usage
3636 local usage = [[
37 ldoc, a documentation generator for Lua, vs 1.3.12
37 ldoc, a documentation generator for Lua, vs 1.4.0
3838 -d,--dir (default doc) output directory
3939 -o,--output (default 'index') output name
4040 -v,--verbose verbose
5050 -x,--ext (default html) output file extension
5151 -c,--config (default config.ld) configuration name
5252 -i,--ignore ignore any 'no doc comment or no module' warnings
53 -X,--not_luadoc break LuaDoc compatibility. Descriptions may continue after tags.
5354 -D,--define (default none) set a flag to be used in config.ld
5455 -C,--colon use colon style
5556 -B,--boilerplate ignore first comment in source files
103104
104105 ProjectMap:add_kind('module','Modules')
105106 ProjectMap:add_kind('script','Scripts')
107 ProjectMap:add_kind('classmod','Classes')
106108 ProjectMap:add_kind('topic','Topics')
107109 ProjectMap:add_kind('example','Examples')
108110
116118 ['.cpp'] = cc,
117119 ['.cxx'] = cc,
118120 ['.C'] = cc,
119 ['.mm'] = cc
121 ['.mm'] = cc,
122 ['.moon'] = lang.moon,
120123 }
121124
122125 ------- ldoc external API ------------
174177 end
175178
176179 function ldoc.manual_url (url)
177 global.set_manual_url(url)
180 global.set_manual_url(url)
178181 end
179182
180183 function ldoc.custom_see_handler(pat, handler)
181 doc.add_custom_see_handler(pat, handler)
184 doc.add_custom_see_handler(pat, handler)
182185 end
183186
184187 local ldoc_contents = {
185188 'alias','add_language_extension','new_type','add_section', 'tparam_alias',
186189 'file','project','title','package','format','output','dir','ext', 'topics',
187190 'one','style','template','description','examples', 'pretty', 'charset', 'plain',
188 'readme','all','manual_url', 'ignore', 'colon',
189 'boilerplate','merge', 'wrap', 'not_luadoc',
191 'readme','all','manual_url', 'ignore', 'colon', 'sort', 'module_file',
192 'boilerplate','merge', 'wrap', 'not_luadoc', 'template_escape',
190193 'no_return_or_parms','no_summary','full_description','backtick_references', 'custom_see_handler',
194 'no_space_before_args',
191195 }
192196 ldoc_contents = tablex.makeset(ldoc_contents)
193197
279283 elseif type(args.file) == 'table' then
280284 for i,f in ipairs(args.file) do
281285 args.file[i] = abspath(f)
282 print(args.file[i])
283286 end
284287 else
285288 args.file = abspath(args.file)
344347 local ext = path.extension(f)
345348 local ftype = file_types[ext]
346349 if ftype then
347 if args.verbose then print(path.basename(f)) end
350 if args.verbose then print(f) end
348351 local F,err = parse.file(f,ftype,args)
349352 if err then
350353 if F then
363366 override 'colon'
364367 override 'merge'
365368 override 'not_luadoc'
369 override 'module_file'
370
371 -- ldoc.module_file establishes a partial ordering where the
372 -- master module files are processed first.
373 local function reorder_module_file ()
374 if args.module_file then
375 local mf = {}
376 for mname, f in pairs(args.module_file) do
377 local fullpath = abspath(f)
378 mf[fullpath] = true
379 end
380 return function(x,y)
381 return mf[x] and not mf[y]
382 end
383 end
384 end
366385
367386 if type(args.file) == 'table' then
368387 -- this can only be set from config file so we can assume it's already read
388 args.file.sortfn = reorder_module_file()
369389 process_file_list(args.file,'*.*',process_file, file_list)
370390 if #file_list == 0 then quit "no source files specified" end
371391 elseif path.isdir(args.file) then
382402 end
383403 end
384404 end
405 -- process files, optionally in order that respects master module files
406 local sortfn = reorder_module_file()
407 if sortfn then files:sort(sortfn) end
385408 for f in files:iter() do
386409 process_file(f, file_list)
387410 end
411
388412 if #file_list == 0 then
389413 quit(quote(args.file).." contained no source files")
390414 end
552576
553577 ldoc.css, ldoc.templ = 'ldoc.css','ldoc.ltp'
554578
579 if args.ext == 'md' then
580 ldoc.templ = 'ldoc.mdtp'
581 ldoc.template_escape = '>'
582 ldoc.style = false
583 args.ext = '.md'
584 end
585
555586 local function style_dir (sname)
556587 local style = ldoc[sname]
557588 local dir
589 if style==false and sname == 'style' then
590 args.style = false
591 ldoc.css = false
592 end
558593 if style then
559594 if style == true then
560595 dir = config_dir
603638 utils.writefile(path.join(tmpdir,name),require('ldoc.html.'..name:gsub('%.','_')))
604639 end
605640 if args.style == '!' then
641 tmpwrite(ldoc.css)
642 args.style = tmpdir
643 end
644 if args.template == '!' then
606645 tmpwrite(ldoc.templ)
607 args.style = tmpdir
608 end
609 if args.template == '!' then
610 tmpwrite(ldoc.css)
611646 args.template = tmpdir
612647 end
613648 end
0 ----
1 -- A list class that wraps a table
2 -- @classmod List
3 import insert,concat,remove from table
4
5 class List
6 --- constructor passed a table `t`, which can be `nil`.
7 new: (t) =>
8 @ls = t or {}
9
10 --- append to list.
11 add: (item) =>
12 insert @ls,item
13
14 --- insert `item` at `idx`
15 insert: (idx,item) =>
16 insert @ls,idx,item
17
18 --- remove item at `idx`
19 remove: (idx) => remove @ls,idx
20
21 --- length of list
22 len: => #@ls
23
24 --- string representation
25 -- @within Metamethods
26 __tostring: => '['..(concat @ls,',')..']'
27
28 --- return idx of first occurence of `item`
29 find: (item) =>
30 for i = 1,#@ls
31 if @ls[i] == item then return i
32
33 --- remove item by value
34 remove_value: (item) =>
35 idx = self\find item
36 self\remove idx if idx
37
38 --- remove a list of items
39 remove_values: (items) =>
40 for item in *items do self\remove_value item
41
42 --- create a sublist of items indexed by a table `indexes`
43 index_by: (indexes) =>
44 List [@ls[idx] for idx in *indexes]
45
46 --- make a copy of this list
47 copy: => List [v for v in *@ls]
48
49 --- append items from the table or list `list`
50 extend: (list) =>
51 other = if list.__class == List then list.ls else list
52 for v in *other do self\add v
53 self
54
55 --- concatenate two lists, giving a new list
56 -- @within Metamethods
57 __concat: (l1,l2) -> l1\copy!\extend l2
58
59 --- an iterator over all items
60 iter: =>
61 i,t,n = 0,@ls,#@ls
62 ->
63 i += 1
64 if i <= n then t[i]
65
66 return List
0 file = 'list.moon'
1 no_return_or_parms=true
2 no_summary=true
3 format = 'markdown'
4 --sort = true
1010
1111 --- first useless function.
1212 -- Optional type specifiers are allowed in this format.
13 -- As an extension, '?' is short for '?|'.
13 -- As an extension, '?T' is short for '?nil|T'.
1414 -- Note how these types are rendered!
1515 -- string: name
1616 -- int: age
17 -- ?person2: options
17 -- ?person3: options
1818 -- treturn: ?table|string
1919 function one (name,age,options)
2020 end
21
22 --- implicit table can always use colon notation.
23 person2 = {
24 id=true, -- string: official ID number
25 sex=true, -- string: one of 'M', 'F' or 'N'
26 spouse=true, -- ?person3: wife or husband
27 }
2128
2229 --- explicit table in colon format.
2330 -- Note how '!' lets you use a type name directly.
1010 -- Note the the standard tparam aliases, and how the 'opt' and 'optchain'
1111 -- modifiers may also be used. If the Lua function has varargs, then
1212 -- you may document an indefinite number of extra arguments!
13 -- @string name person's name
13 -- @tparam ?string|Person name person's name
1414 -- @int age
1515 -- @string[opt='gregorian'] calender optional calendar
1616 -- @int[opt=0] offset optional offset
2626 function two (one,two,three,four)
2727 end
2828
29
3029 --- third useless function.
3130 -- Can always put comments inline, may
3231 -- be multiple.
3635 age -- int:
3736 -- not less than zero!
3837 )
38
39 ---- function with single optional arg
40 -- @param[opt] one
41 function four (one)
42 end
3943
4044 --- an implicit table.
4145 -- Again, we can use the comments
7676 return front_elem[PRIORITY_KEY], front_elem[VALUE_KEY]
7777 end
7878
79 --- construct a @{priority_queue}.
79 --- construct a `priority_queue`.
8080 -- @constructor
8181 make_priority_queue = function()
8282 --- @export