Commit 7e534973932d03cc714182930743ec9d2440311a - lua-ldoc

updated 1.3 docs steve donovan 11 years ago

2 changed file(s) with 478 addition(s) and 159 deletion(s). Raw diff Collapse all Expand all

+454

-150

docs/doc.md less more

1	1
2	2	## Introduction
3	3
4		LDoc is a second-generation documentation tool that can be used as a replacement for [LuaDoc](http://keplerproject.github.com/luadoc/). It arose out of my need to document my own projects and only depends on the [Penlight](https://github.com/stevedonovan/Penlight) libraries.
5
6		It is mostly compatible with LuaDoc, except that certain workarounds are no longer needed. For instance, it is not so married to the idea that Lua modules should be defined using the `module` function; this is not only a matter of taste since this has been deprecated in Lua 5.2.
7
8		Otherwise, the output is very similar, which is no accident since the HTML templates are based directly on LuaDoc. You can ship your own customized templates and style sheets with your [own project](http://nilnor.github.com/textui/docs/), however. You have an option to use Markdown to process the documentation, which means no ugly HTML is needed in doc comments. C/C++ extension modules may be documented in a similar way, although function names cannot be inferred from the code itself.
9
10		LDoc can provide integrated documentation, with traditional function comments, any documents in Markdown format, and specified source examples. Lua source in examples and the documents will be prettified.
11
12		Although there are a fair number of command-line options, the preferred route is to write a `config.ld` configuration file in Lua format. By convention, if LDoc is simply invoked as `ldoc .` it will read this file first. In this way, the aim is to make it very easy for end-users to build your documentation using this simple command.
	4	LDoc is a second-generation documentation tool that can be used as a replacement for
	5	[LuaDoc](http://keplerproject.github.com/luadoc/). It arose out of my need to document my
	6	own projects and only depends on the [Penlight](https://github.com/stevedonovan/Penlight)
	7	libraries.
	8
	9	It is mostly compatible with LuaDoc, except that certain workarounds are no longer needed.
	10	For instance, it is not so married to the idea that Lua modules should be defined using the
	11	`module` function; this is not only a matter of taste since this has been deprecated in Lua
	12	5.2.
	13
	14	Otherwise, the output is very similar, which is no accident since the HTML templates are
	15	based directly on LuaDoc. You can ship your own customized templates and style sheets with
	16	your [own project](http://nilnor.github.com/textui/docs/), however. You have an option to
	17	use Markdown to process the documentation, which means no ugly HTML is needed in doc
	18	comments. C/C++ extension modules may be documented in a similar way, although function
	19	names cannot be inferred from the code itself.
	20
	21	LDoc can provide integrated documentation, with traditional function comments, any documents
	22	in Markdown format, and specified source examples. Lua source in examples and the documents
	23	will be prettified.
	24
	25	Although there are a fair number of command-line options, the preferred route is to write a
	26	`config.ld` configuration file in Lua format. By convention, if LDoc is simply invoked as
	27	`ldoc .` it will read this file first. In this way, the aim is to make it very easy for
	28	end-users to build your documentation using this simple command.
13	29
14	30	## Commenting Conventions
15	31
16	32	LDoc follows the conventions established by Javadoc and later by LuaDoc.
17	33
18		Only 'doc comments' are parsed; these can be started with at least 3 hyphens, or by a empty comment line with at least 3 hypens:
	34	Only 'doc comments' are parsed; these can be started with at least 3 hyphens, or by a empty
	35	comment line with at least 3 hypens:
19	36
20	37	--- summary.
21	38	-- Description; this can extend over

31	48	...;
32	49	]]
33	50
34		Any module or script must start with a doc comment; any other files are ignored and a warning issued. The only exception is if the module starts with an explicit `module` statement.
35
36		All doc comments start with a summary sentence, that ends with a period or a question mark. An optional description may follow. Normally the summary sentence will appear in the module contents.
37
38		After this descriptive text, there will typically be _tags_. These follow the convention established by Javadoc and widely used in tools for other languages.
	51	Any module or script must start with a doc comment; any other files are ignored and a
	52	warning issued. The only exception is if the module starts with an explicit `module`
	53	statement.
	54
	55	All doc comments start with a summary sentence, that ends with a period or a question mark.
	56	An optional description may follow. Normally the summary sentence will appear in the module
	57	contents.
	58
	59	After this descriptive text, there will typically be _tags_. These follow the convention
	60	established by Javadoc and widely used in tools for other languages.
39	61
40	62	--- foo explodes text.
41	63	-- It is a specialized splitting operation on a string.

50	72	-- @tparam string text the string
51	73	-- @treturn {string,...} a table of substrings
52	74
53		There may be multiple 'param' tags, which should document each formal parameter of the function. For Lua, there can also be multiple 'return' tags
	75	There may be multiple 'param' tags, which should document each formal parameter of the
	76	function. For Lua, there can also be multiple 'return' tags
54	77
55	78	--- solvers for common equations.
56	79	module("solvers", package.seeall)

74	97
75	98	...
76	99
77		This is the common module style used in Lua 5.1, but it's increasingly common to see less 'magic' ways of creating modules in Lua. Since `module` is deprecated in Lua 5.2, any future-proof documentation tool needs to handle these styles gracefully:
	100	This is the common module style used in Lua 5.1, but it's increasingly common to see less
	101	'magic' ways of creating modules in Lua. Since `module` is deprecated in Lua 5.2, any
	102	future-proof documentation tool needs to handle these styles gracefully:
78	103
79	104	--- a test module
80	105	-- @module test

90	115
91	116	return test
92	117
93		Here the name of the module is explicitly given using the 'module' tag. If you leave this out, then LDoc will infer the name of the module from the name of the file and its relative location in the filesystem; this logic is also used for the `module(...)` idiom. (How this works and when you need to provide extra information is discussed later.)
94
95		It is common to use a local name for a module when declaring its contents. In this case the 'alias' tag can tell LDoc that these functions do belong to the module:
	118	Here the name of the module is explicitly given using the 'module' tag. If you leave this
	119	out, then LDoc will infer the name of the module from the name of the file and its relative
	120	location in the filesystem; this logic is also used for the `module(...)` idiom. (How this
	121	works and when you need to provide extra information is discussed later.)
	122
	123	It is common to use a local name for a module when declaring its contents. In this case the
	124	'alias' tag can tell LDoc that these functions do belong to the module:
96	125
97	126	--- another test.
98	127	-- @module test2

107	136
108	137	return M
109	138
110		`M` and `_M` are used commonly enough that LDoc will recognize them as aliases automatically, but 'alias' allows you to use any identifier.
111
112		LDoc tries to deduce the function name and the formal parameter names from examining the code after the doc comment. It also recognizes the 'unsugared' way of defining functions as explicit assignment to a variable:
	139	`M` and `_M` are used commonly enough that LDoc will recognize them as aliases
	140	automatically, but 'alias' allows you to use any identifier.
	141
	142	LDoc tries to deduce the function name and the formal parameter names from examining the
	143	code after the doc comment. It also recognizes the 'unsugared' way of defining functions as
	144	explicit assignment to a variable:
113	145
114	146	--- second test.
115	147	M.two = function(...) ... end
116	148
117		Apart from exported functions, a module usually contains local functions. By default, LDoc does not include these in the documentation, but they can be enabled using the `--all` flag. They can be documented just like 'public' functions:
	149	Apart from exported functions, a module usually contains local functions. By default, LDoc
	150	does not include these in the documentation, but they can be enabled using the `--all` flag.
	151	They can be documented just like 'public' functions:
118	152
119	153	--- it's clear that boo is local from context.
120	154	local function boo(...) .. end

125	159	-- @local here
126	160	function foo(...) .. end
127	161
128		Modules can of course export tables and other values. The classic way to document a table looks like this:
	162	Modules can of course export tables and other values. The classic way to document a table
	163	looks like this:
129	164
130	165	--- a useful table of constants
131	166	-- @field alpha first correction

133	168	-- @field gamma fudge factor
134	169	-- @table constants
135	170
136		Here the kind of item is made explicit by the 'table' tag; tables have 'fields' in the same way as functions have parameters.
	171	Here the kind of item is made explicit by the 'table' tag; tables have 'fields' in the same
	172	way as functions have parameters.
137	173
138	174	This can get tedious, so LDoc will attempt to extract table documentation from code:
139	175

144	180	gamma = 0.01 -- fudge factor
145	181	}
146	182
147		The rule followed here is `NAME = <table-constructor>`. If LDoc can't work out the name and type from the following code, then a warning will be issued, pointing to the file and location.
	183	The rule followed here is `NAME = <table-constructor>`. If LDoc can't work out the name and
	184	type from the following code, then a warning will be issued, pointing to the file and
	185	location.
148	186
149	187	Another kind of module-level type is 'field', such as follows:
150	188

159	197	-- @field _CONTENTS
160	198	M._CONTENTS = {constants=true,one=true,...}
161	199
162		The order of tags is not important, but as always, consistency is useful. Tags like 'param' and 'return' can be specified multiple times, whereas a type tag like 'function' can only occur once in a comment. The basic rule is that a single doc comment can only document one entity.
163
164		By default, LDoc will process any file ending in '.lua' or '.luadoc' in a specified directory; you may point it to a single file as well. A 'project' usually consists of many modules in one or more _packages_. The generated `index.html` will point to the generated documentation for each of these modules.
165
166		If only one module or script is documented for a project, then the `index.html` generated contains the documentation for that module, since an index pointing to one module would be redundant.
	200	The order of tags is not important, but as always, consistency is useful. Tags like 'param'
	201	and 'return' can be specified multiple times, whereas a type tag like 'function' can only
	202	occur once in a comment. The basic rule is that a single doc comment can only document one
	203	entity.
	204
	205	By default, LDoc will process any file ending in '.lua' or '.luadoc' in a specified
	206	directory; you may point it to a single file as well. A 'project' usually consists of many
	207	modules in one or more _packages_. The generated `index.html` will point to the generated
	208	documentation for each of these modules.
	209
	210	If only one module or script is documented for a project, then the `index.html` generated
	211	contains the documentation for that module, since an index pointing to one module would be
	212	redundant.
167	213
168	214	(If you want to document a script, there is a project-level type 'script' for that.)
169	215
170	216	## See References
171	217
172		The tag 'see' is used to reference other parts of the documentation, and 'usage' can provide examples of use:
	218	The tag 'see' is used to reference other parts of the documentation, and 'usage' can provide
	219	examples of use:
173	220
174	221	---------
175	222	-- split a string in two.

181	228	-- @see split
182	229	funtion split2(s,delim) .. end
183	230
184		Here it's assumed that 'split' is a function defined in the same module. If you wish to link to a function in another module, then the reference has to be qualified.
185
186		References to methods use a colon: `myclass:method`; this is for instance how you would refer to members of a `@type` section.
	231	Here it's assumed that 'split' is a function defined in the same module. If you wish to link
	232	to a function in another module, then the reference has to be qualified.
	233
	234	References to methods use a colon: `myclass:method`; this is for instance how you would
	235	refer to members of a `@type` section.
187	236
188	237	The example at `tests/complex` shows how @see references are interpreted:
189	238

193	242	complex.display
194	243	complex
195	244
196		You may of course use the full name of a module or function, but can omit the top-level namespace - e.g. can refer to the module `util` and the function `display.display_that` directly. Within a module, you can directly use a function name, e.g. in `display` you can say `display_this`.
197
198		What applies to functions also applies to any module-level item like tables. New module-level items can be defined and they will work according to these rules.
199
200		If a reference is not found within the project, LDoc checks to see if it is a reference to a Lua standard function or table, and links to the online Lua manual. So references like 'table.concat' are handled sensibly.
201
202		References may be made inline using the @\{ref} syntax. This may appear anywhere in the text, and is more flexible than @see. In particular, it provides one way to document the type of a parameter or return value when that type has a particular structure:
	245	You may of course use the full name of a module or function, but can omit the top-level
	246	namespace - e.g. can refer to the module `util` and the function `display.display_that`
	247	directly. Within a module, you can directly use a function name, e.g. in `display` you can
	248	say `display_this`.
	249
	250	What applies to functions also applies to any module-level item like tables. New
	251	module-level items can be defined and they will work according to these rules.
	252
	253	If a reference is not found within the project, LDoc checks to see if it is a reference to a
	254	Lua standard function or table, and links to the online Lua manual. So references like
	255	'table.concat' are handled sensibly.
	256
	257	References may be made inline using the @\{ref} syntax. This may appear anywhere in the
	258	text, and is more flexible than @see. In particular, it provides one way to document the
	259	type of a parameter or return value when that type has a particular structure:
203	260
204	261	------
205	262	-- extract standard variables.

216	273	-- @field viscosity
217	274	-- @table stdvars
218	275
219		@\{ref} is very useful for referencing your API from code samples and readme text. (I've had to throw in a spurious backspace to stop expansion in this example.)
	276	@\{ref} is very useful for referencing your API from code samples and readme text. (I've had
	277	to throw in a spurious backspace to stop expansion in this example.)
220	278
221	279	The link text can be changed from the default by the extended syntax @\{ref\|text}.
222	280
223		You can also put references in backticks, like `\`stdvars\``. This is commonly used in Markdown to indicate code, so it comes naturally when writing documents. It is controlled by the configuration variable `backtick_references`; the default is `true` if you use Markdown in your project, but can be specified explicitly in your `config.ld`.
	281	You can also put references in backticks, like `\`stdvars\``. This is commonly used in
	282	Markdown to indicate code, so it comes naturally when writing documents. It is controlled by
	283	the configuration variable `backtick_references`; the default is `true` if you use Markdown
	284	in your project, but can be specified explicitly in your `config.ld`.
	285
	286	### Custom @see References
	287
	288	It's useful to define how to handle references external to a project. For instance, in the
	289	[luaposix](https://github.com/luaposix/luaposix) project we wanted to have `man` references
	290	to the corresponding C function:
	291
	292	------------
	293	-- raise a signal on this process.
	294	-- @see raise(3)
	295	-- @int nsig
	296	-- @return integer error cod
	297	function raise (nsig)
	298	end
	299
	300	These see references always have this particular form, and the task is to turn them into
	301	online references to the Linux manpages. So in `config.ld` we have:
	302
	303	local upat = "http://www.kernel.org/doc/man-pages/online/pages/man%s/%s.%s.html"
	304
	305	custom_see_handler('^(%a+)%((%d)%)$',function(name,section)
	306	local url = upat:format(section,name,section)
	307	local name = name .. '(' ..section..')'
	308	return name, url
	309	end)
	310
	311	'^(%a+)%((%d)%)$' both matches the pattern and extracts the name and its section. THen it's
	312	a simple matter of building up the appropriate URL. The function is expected to
	313	return _link text_ and _link source_ and the patterns are checked before LDoc tries to resolve
	314	project references. So it is best to make them match as exactly as possible.
224	315
225	316	## Sections
226	317
227		LDoc supports _explicit_ sections. By default, the sections correspond to the pre-existing types in a module: 'Functions', 'Tables' and 'Fields' (There is another default section 'Local Functions' which only appears if LDoc is invoked with the `--all` flag.) But new sections can be added; the first mechanism is when you define a new type (say 'macro') a new section ('Macros') is created to contain these types. There is also a way to declare ad-hoc sections using the `@section` tag.
228
229		The need occurs when a module has a lot of functions that need to be put into logical sections.
	318	LDoc supports _explicit_ sections. By default, the sections correspond to the pre-existing
	319	types in a module: 'Functions', 'Tables' and 'Fields' (There is another default section
	320	'Local Functions' which only appears if LDoc is invoked with the `--all` flag.) But new
	321	sections can be added; the first mechanism is when you define a new type (say 'macro') a new
	322	section ('Macros') is created to contain these types. There is also a way to declare ad-hoc
	323	sections using the `@section` tag.
	324
	325	The need occurs when a module has a lot of functions that need to be put into logical
	326	sections.
230	327
231	328	--- File functions.
232	329	-- Useful utilities for opening foobar format files.

244	341
245	342	...
246	343
247		A section doc-comment has the same structure as a normal doc-comment; the summary is used as the new section title, and the description will be output at the start of the function details for that section.
248
249		In any case, sections appear under 'Contents' on the left-hand side. See the [winapi](http://stevedonovan.github.com/winapi/api.html) documentation for an example of how this looks.
250
251		Arguably a module writer should not write such very long modules, but it is not the job of the documentation tool to limit the programmer!
252
253		A specialized kind of section is `type`: it is used for documenting classes. The functions (or fields) within a type section are considered to be the methods of that class.
	344	A section doc-comment has the same structure as a normal doc-comment; the summary is used as
	345	the new section title, and the description will be output at the start of the function
	346	details for that section.
	347
	348	In any case, sections appear under 'Contents' on the left-hand side. See the
	349	[winapi](http://stevedonovan.github.com/winapi/api.html) documentation for an example of how
	350	this looks.
	351
	352	Arguably a module writer should not write such very long modules, but it is not the job of
	353	the documentation tool to limit the programmer!
	354
	355	A specialized kind of section is `type`: it is used for documenting classes. The functions
	356	(or fields) within a type section are considered to be the methods of that class.
254	357
255	358	--- A File class.
256	359	-- @type File

262	365	...
263	366	end
264	367
265		(In an ideal world, we would use the word 'class' instead of 'type', but this would conflict with the LuaDoc usage.)
	368	(In an ideal world, we would use the word 'class' instead of 'type', but this would conflict
	369	with the LuaDoc usage.)
266	370
267	371	A section continues until the next section is found, `@section end`, or end of file.
268	372
269
	373	You can put items into an implicit section using the @within tag. This allows you to put
	374	adjacent functions in different sections, so that you are not forced to order your code
	375	in a particular way.
	376
	377	Sometimes a module may logically span several files. There will be a master module with name
	378	'foo' and other files which when required add functions to that module. If these files have
	379	a @submodule tag, their contents will be placed in the master module documentation. However,
	380	a current limitation is that the master module must be processed before the submodules.
	381
	382	See the `tests/submodule` example for how this works in practice.
270	383
271	384	## Differences from LuaDoc
272	385

285	398	-- (LDoc)
286	399	-- @module simple
287	400
288		This is because type names (like 'function', 'module', 'table', etc) can function as tags. LDoc also provides a means to add new types (e.g. 'macro') using a configuration file which can be shipped with the source. If you become bored with typing 'param' repeatedly then you can define an alias for it, such as 'p'. This can also be specified in the configuration file.
289
290		LDoc will also work with C/C++ files, since extension writers clearly have the same documentation needs as Lua module writers.
	401	This is because type names (like 'function', 'module', 'table', etc) can function as tags.
	402	LDoc also provides a means to add new types (e.g. 'macro') using a configuration file which
	403	can be shipped with the source. If you become bored with typing 'param' repeatedly then you
	404	can define an alias for it, such as 'p'. This can also be specified in the configuration file.
	405
	406	LDoc will also work with C/C++ files, since extension writers clearly have the same
	407	documentation needs as Lua module writers.
291	408
292	409	LDoc gives the documenter the option to use Markdown to parse the contents of comments.
293	410
294	411	## Adding new Tags
295	412
296		LDoc tries to be faithful to LuaDoc, but provides some extensions. Aliases for tags can be defined, and new types declared.
	413	LDoc tries to be faithful to LuaDoc, but provides some extensions. Aliases for tags can be
	414	defined, and new types declared.
297	415
298	416	--- zero function. Two new ldoc features here; item types
299	417	-- can be used directly as tags, and aliases for tags

302	420	-- @p k1 first
303	421	-- @p k2 second
304	422
305		Here an alias for 'param' has been defined. If a file `config.ld` is found in the source, then it will be loaded as Lua data. For example, the configuration for the above module provides a title and defines an alias for 'param':
	423	Here an alias for 'param' has been defined. If a file `config.ld` is found in the source,
	424	then it will be loaded as Lua data. For example, the configuration for the above module
	425	provides a title and defines an alias for 'param':
306	426
307	427	title = "testmod docs"
308	428	project = "testmod"

323	443
324	444	## Inferring more from Code
325	445
326		The qualified name of a function will be inferred from any `function` keyword following the doc comment. LDoc goes further with this kind of code analysis, however.
	446	The qualified name of a function will be inferred from any `function` keyword following the
	447	doc comment. LDoc goes further with this kind of code analysis, however.
327	448
328	449	Instead of:
329	450

375	496	static int l_createtable (lua_State *L) {
376	497	....
377	498
378		Both `/**` and `///` are recognized as starting a comment block. Otherwise, the tags are processed in exactly the same way. It is necessary to specify that this is a function with a given name, since this cannot be reliably be inferred from code. Such a file will need a module comment, which is treated exactly as in Lua.
379
380		An unknown extension can be associated with a language using a call like `add_language_extension('lc','c')` in `config.ld`. (Currently the language can only be 'c' or 'lua'.)
	499	Both `/**` and `///` are recognized as starting a comment block. Otherwise, the tags are
	500	processed in exactly the same way. It is necessary to specify that this is a function with a
	501	given name, since this cannot be reliably be inferred from code. Such a file will need a
	502	module comment, which is treated exactly as in Lua.
	503
	504	An unknown extension can be associated with a language using a call like
	505	`add_language_extension('lc','c')` in `config.ld`. (Currently the language can only be 'c'
	506	or 'lua'.)
381	507
382	508	See 'tests/examples/mylib.c' for the full example.
383	509

388	514	$ ldoc lua
389	515	output written to docs/
390	516
391		Thereafter the `docs` directory will contain `index.html` which points to individual modules in the `modules` subdirectory. The `--dir` flag can specify where the output is generated, and will ensure that the directory exists. The output structure is like LuaDoc: there is an `index.html` and the individual modules are in the `modules` subdirectory. This applies to all project-level types, so that you can also get `scripts`, `examples` and `topics` directories.
392
393		If your modules use `module(...)` then the module name has to be deduced. If `ldoc` is run from the root of the package, then this deduction does not need any help - e.g. if your package was `foo` then `ldoc foo` will work as expected. If we were actually in the `foo` directory then `ldoc -b .. .` will correctly deduce the module names. An example would be generating documentation for LuaDoc itself:
	517	Thereafter the `docs` directory will contain `index.html` which points to individual modules
	518	in the `modules` subdirectory. The `--dir` flag can specify where the output is generated,
	519	and will ensure that the directory exists. The output structure is like LuaDoc: there is an
	520	`index.html` and the individual modules are in the `modules` subdirectory. This applies to
	521	all project-level types, so that you can also get `scripts`, `examples` and `topics`
	522	directories.
	523
	524	If your modules use `module(...)` then the module name has to be deduced. If `ldoc` is run
	525	from the root of the package, then this deduction does not need any help - e.g. if your
	526	package was `foo` then `ldoc foo` will work as expected. If we were actually in the `foo`
	527	directory then `ldoc -b .. .` will correctly deduce the module names. An example would be
	528	generating documentation for LuaDoc itself:
394	529
395	530	$ ldoc -b .. /path/to/luadoc
396	531
397		Without the `-b` setting the base of the package to the _parent_ of the directory, implicit modules like `luadoc.config` will be incorrectly placed in the global namespace.
398
399		For new-style modules, that don't use `module()`, it is recommended that the module comment has an explicit `@module PACKAGE.NAME`. If it does not, then `ldoc` will still attempt to deduce the module name, but may need help with `--package/-b` as above.
400
401		`format = 'markdown'` can be used in your `config.ld` and will be used to process summaries and descriptions. This requires [markdown.lua](http://www.frykholm.se/files/markdown.lua) by Niklas Frykholm to be installed (this can be most easily done with `luarocks install markdown`.) A much faster alternative is [lua-discount](http://asbradbury.org/projects/lua-discount/) which you can use by setting `format` to 'discount' after installing using `luarocks install lua-discount`) The [discount](http://www.pell.portland.or.us/~orc/Code/discount/) Markdown processor additionally has more features than the pure Lua version, such as PHP-Extra style tables. As a special case, LDoc will fall back to using `markdown.lua` if it cannot find `discount`.
402
403		A special case is if you simply say 'ldoc .'. Then there _must_ be a `config.ld` file available in the directory, and it can specify the file:
	532	Without the `-b` setting the base of the package to the _parent_ of the directory, implicit
	533	modules like `luadoc.config` will be incorrectly placed in the global namespace.
	534
	535	For new-style modules, that don't use `module()`, it is recommended that the module comment
	536	has an explicit `@module PACKAGE.NAME`. If it does not, then `ldoc` will still attempt to
	537	deduce the module name, but may need help with `--package/-b` as above.
	538
	539	`format = 'markdown'` can be used in your `config.ld` and will be used to process summaries
	540	and descriptions. This requires [markdown.lua](http://www.frykholm.se/files/markdown.lua) by
	541	Niklas Frykholm to be installed (this can be most easily done with `luarocks install
	542	markdown`.) A much faster alternative is
	543	[lua-discount](http://asbradbury.org/projects/lua-discount/) which you can use by setting
	544	`format` to 'discount' after installing using `luarocks install lua-discount`) The
	545	[discount](http://www.pell.portland.or.us/~orc/Code/discount/) Markdown processor
	546	additionally has more features than the pure Lua version, such as PHP-Extra style tables.
	547	As a special case, LDoc will fall back to using `markdown.lua` if it cannot find `discount`.
	548
	549	`format = 'markdown'` can be used in your `config.ld` and will be used to process summaries
	550	and descriptions. This requires a markdown processor.
	551	LDoc knows how to use:
	552
	553	- [markdown.lua](http://www.frykholm.se/files/markdown.lua) a pure Lua processor by
	554	Niklas Frykholm (this can be installed easily with `luarocks install markdown`.)
	555	- [lua-discount](http://asbradbury.org/projects/lua-discount/), a faster alternative
	556	(installed with `luarocks install lua-discount`). lua-discount uses the C
	557	[discount](http://www.pell.portland.or.us/~orc/Code/discount/) Markdown processor which has
	558	more features than the pure Lua version, such as PHP-Extra style tables.
	559	- [lunamark](http://jgm.github.com/lunamark/), another pure Lua processor, faster than
	560	markdown, and with extra features (`luarocks install lunamark`).
	561
	562	You can request the processor you like with `format = 'markdown\|discount\|lunamark'`, and
	563	LDoc will attempt to use it. If it can't find it, it will look for one of the other
	564	markdown processors. If it can't find any markdown processer, it will fall back to text
	565	processing.
	566
	567
	568	A special case is if you simply say 'ldoc .'. Then there _must_ be a `config.ld` file
	569	available in the directory, and it can specify the file:
404	570
405	571	file = "mymod.lua"
406	572	title = "mymod documentation"
407	573	description = "mymod does some simple but useful things"
408	574
409		`file` can of course point to a directory, just as with the `--file` option. This mode makes it particularly easy for the user to build the documentation, by allowing you to specify everything explicitly in the configuration.
410
411		In `config.ld`, `file` may be a Lua table, containing file names or directories; if it has an `exclude` field then that will be used to exclude files from the list, for example `{'examples', exclude = {'examples/slow.lua'}}`.
	575	`file` can of course point to a directory, just as with the `--file` option. This mode makes
	576	it particularly easy for the user to build the documentation, by allowing you to specify
	577	everything explicitly in the configuration.
	578
	579	In `config.ld`, `file` may be a Lua table, containing file names or directories; if it has
	580	an `exclude` field then that will be used to exclude files from the list, for example
	581	`{'examples', exclude = {'examples/slow.lua'}}`.
412	582
413	583
414	584	## Processing Single Modules
415	585
416		`--output` can be used to give the output file a different name. This is useful for the special case when a single module file is specified. Here an index would be redundant, so the single HTML file generated contains the module documentation.
	586	`--output` can be used to give the output file a different name. This is useful for the
	587	special case when a single module file is specified. Here an index would be redundant, so
	588	the single HTML file generated contains the module documentation.
417	589
418	590	$ ldoc mylib.lua --> results in docs/index.html
419	591	$ ldoc --output mylib mylib.lua --> results in docs/mylib.html
420	592	$ ldoc --output mylib --dir html mylib.lua --> results in html/mylib.html
421	593
422		The default sections used by LDoc are 'Functions', 'Tables' and 'Fields', corresponding to the built-in types 'function', 'table' and 'field'. If `config.ld` contains something like `new_type("macro","Macros")` then this adds a new section 'Macros' which contains items of 'macro' type - 'macro' is registered as a new valid tag name. The default template then presents items under their corresponding section titles, in order of definition.
	594	The default sections used by LDoc are 'Functions', 'Tables' and 'Fields', corresponding to
	595	the built-in types 'function', 'table' and 'field'. If `config.ld` contains something like
	596	`new_type("macro","Macros")` then this adds a new section 'Macros' which contains items of
	597	'macro' type - 'macro' is registered as a new valid tag name. The default template then
	598	presents items under their corresponding section titles, in order of definition.
423	599
424	600	## Getting Help about a Module
425	601
426		There is an option to simply dump the results of parsing modules. Consider the C example `tests/example/mylib.c':
	602	There is an option to simply dump the results of parsing modules. Consider the C example
	603	`tests/example/mylib.c':
427	604
428	605	@plain
429	606	$ ldoc --dump mylib.c

443	620	c constant
444	621	return {"first root","second root"}
445	622
446		This is useful to quickly check for problems; here we see that `createable` did not have a return tag.
447
448		LDoc takes this idea of data dumping one step further. If used with the `-m` flag it will look up an installed Lua module and parse it. If it has been marked up in LuaDoc-style then you will get a handy summary of the contents:
	623	This is useful to quickly check for problems; here we see that `createable` did not have a
	624	return tag.
	625
	626	LDoc takes this idea of data dumping one step further. If used with the `-m` flag it will
	627	look up an installed Lua module and parse it. If it has been marked up in LuaDoc-style then
	628	you will get a handy summary of the contents:
449	629
450	630	@plain
451	631	$ ldoc -m pl.pretty

482	662	v
483	663	message
484	664
485		Thanks to mitchell's [TextAdept](http://code.google.com/p/textadept/) project, LDoc has a set of `.luadoc` files for all the standard tables, plus [LuaFileSystem](http://keplerproject.github.com/luafilesystem/) and [LPeg](http://www.inf.puc-rio.br/~roberto/lpeg/lpeg.html).
	665	Thanks to mitchell's [TextAdept](http://code.google.com/p/textadept/) project, LDoc has a
	666	set of `.luadoc` files for all the standard tables, plus
	667	[LuaFileSystem](http://keplerproject.github.com/luafilesystem/) and
	668	[LPeg](http://www.inf.puc-rio.br/~roberto/lpeg/lpeg.html).
486	669
487	670	@plain
488	671	$> ldoc -m lfs.lock

503	686
504	687	## Anatomy of a LDoc-generated Page
505	688
506		[winapi](http://stevedonovan.github.com/winapi/api.html) can be used as a good example of a module that uses extended LDoc features.
	689	[winapi](http://stevedonovan.github.com/winapi/api.html) can be used as a good example of a
	690	module that uses extended LDoc features.
507	691
508	692	The _navigation section_ down the left has several parts:
509	693

512	696	- ''Contents'' of the current page
513	697	- ''Modules'' listing all the modules in this project
514	698
515		Note that `description` will be passed through Markdown, if it has been specified for the project. This gives you an opportunity to make lists of links, etc; any '##' headers will be formatted like the other top-level items on the navigation bar.
516
517		'Contents' is automatically generated. It will contain any explicit sections, if they have been used. Otherwise you will get the usual categories: 'Functions', 'Tables' and 'Fields'.
518
519		'Modules' will appear for any project providing Lua libraries; there may also be a 'Scripts' section if the project contains Lua scripts. For example, [LuaMacro](http://stevedonovan.github.com/LuaMacro/docs/api.html) has a driver script `luam` in this section. The [builtin](http://stevedonovan.github.com/LuaMacro/docs/modules/macro.builtin.html) module only defines macros, which are defined as a _custom tag type_.
	699	Note that `description` will be passed through Markdown, if it has been specified for the
	700	project. This gives you an opportunity to make lists of links, etc; any '##' headers will be
	701	formatted like the other top-level items on the navigation bar.
	702
	703	'Contents' is automatically generated. It will contain any explicit sections, if they have
	704	been used. Otherwise you will get the usual categories: 'Functions', 'Tables' and 'Fields'.
	705
	706	'Modules' will appear for any project providing Lua libraries; there may also be a 'Scripts'
	707	section if the project contains Lua scripts. For example,
	708	[LuaMacro](http://stevedonovan.github.com/LuaMacro/docs/api.html) has a driver script `luam`
	709	in this section. The
	710	[builtin](http://stevedonovan.github.com/LuaMacro/docs/modules/macro.builtin.html) module
	711	only defines macros, which are defined as a _custom tag type_.
520	712
521	713	The _content section_ on the right shows:
522	714

524	716	- The contents summary, per section as above
525	717	- The detailed documentation for each item
526	718
527		As before, the description can use Markdown. The summary contains the contents of each section as a table, with links to the details. This is where the difference between an item's summary and an item's description is important; the first will appear in the contents summary. The item details show the item name and its summary again, followed by the description. There are then sections for the following tags: 'param', 'usage', 'return' and 'see' in that order. (For tables, 'Fields' is used instead of 'Parameters' but internally fields of a table are stored as the 'param' tag.)
528
529		You can of course customize the default template, but there are some parameters that can control what the template will generate. Setting `one` to `true` in your configuration file will give a _one-column_ layout, which can be easier to use as a programming reference. You can suppress the contents summary with `no_summary`.
	719	As before, the description can use Markdown. The summary contains the contents of each
	720	section as a table, with links to the details. This is where the difference between an
	721	item's summary and an item's description is important; the first will appear in the contents
	722	summary. The item details show the item name and its summary again, followed by the
	723	description. There are then sections for the following tags: 'param', 'usage', 'return' and
	724	'see' in that order. (For tables, 'Fields' is used instead of 'Parameters' but internally
	725	fields of a table are stored as the 'param' tag.)
	726
	727	You can of course customize the default template, but there are some parameters that can
	728	control what the template will generate. Setting `one` to `true` in your configuration file
	729	will give a _one-column_ layout, which can be easier to use as a programming reference. You
	730	can suppress the contents summary with `no_summary`.
530	731
531	732	## Customizing the Page
532	733
533		Setting `no_return_or_parms` to `true` will suppress the display of 'param' and 'return' tags. This may appeal to programmers who dislike the traditional @tag soup xDoc style and prefer to comment functions just with a description. This is particularly useful when using Markdown in a stylized way to specify arguments:
	734	Setting `no_return_or_parms` to `true` will suppress the display of 'param' and 'return'
	735	tags. This may appeal to programmers who dislike the traditional @tag soup xDoc style and
	736	prefer to comment functions just with a description. This is particularly useful when using
	737	Markdown in a stylized way to specify arguments:
534	738
535	739	---------
536	740	-- This extracts the shortest common substring from the strings _s1_ and _s2_

538	742
539	743	Here I've chosen to italicise parameter names; the main thing is to be consistent.
540	744
541		This style is close to the Python [documentation standard](http://docs.python.org/library/array.html#module-array), especially when used with `no_summary`.
542
543		It is also very much how the Lua documentation is ordered. For instance, this configuration file formats the built-in documentation for the Lua global functions in a way which is close to the original:
	745	This style is close to the Python [documentation
	746	standard](http://docs.python.org/library/array.html#module-array), especially when used with
	747	`no_summary`.
	748
	749	It is also very much how the Lua documentation is ordered. For instance, this configuration
	750	file formats the built-in documentation for the Lua global functions in a way which is close
	751	to the original:
544	752
545	753	project = 'Lua'
546	754	description = 'Lua Standard Libraries'

550	758	format = 'discount'
551	759
552	760
553		Generally, using Markdown gives you the opportunity to structure your documentation in any way you want; particularly if using lua-discount and its [table syntax](http://michelf.com/projects/php-markdown/extra/#table); the desired result can often be achieved then by using a custom style sheet.
	761	Generally, using Markdown gives you the opportunity to structure your documentation in any
	762	way you want; particularly if using lua-discount and its [table
	763	syntax](http://michelf.com/projects/php-markdown/extra/#table); the desired result can often
	764	be achieved then by using a custom style sheet.
554	765
555	766	## Examples
556	767
557		It has been long known that documentation generated just from the source is not really adequate to explain _how_ to use a library. People like reading narrative documentation, and they like looking at examples. Previously I found myself dealing with source-generated and writer-generated documentation using different tools, and having to match these up.
558
559		LDoc allows for source examples to be included in the documentation. For example, see the online documentation for [winapi](http://stevedonovan.github.com/winapi/api.html). The function `utf8_expand` has a `@see` reference to 'testu.lua' and following that link gives you a pretty-printed version of the code.
	768	It has been long known that documentation generated just from the source is not really
	769	adequate to explain _how_ to use a library. People like reading narrative documentation,
	770	and they like looking at examples. Previously I found myself dealing with source-generated
	771	and writer-generated documentation using different tools, and having to match these up.
	772
	773	LDoc allows for source examples to be included in the documentation. For example, see the
	774	online documentation for [winapi](http://stevedonovan.github.com/winapi/api.html). The
	775	function `utf8_expand` has a `@see` reference to 'testu.lua' and following that link gives
	776	you a pretty-printed version of the code.
560	777
561	778	The line in the `config.ld` that enables this is:
562	779
563	780	examples = {'examples', exclude = {'examples/slow.lua'}}
564	781
565		That is, all files in the `examples` folder are to be pretty-printed, except for `slow.lua` which is meant to be called from one of the examples. The see-reference to `testu.lua` resolves to 'examples/testu.lua.html'.
566
567		Examples may link back to the API documentation, for instance the example `input.lua` has a @\{spawn_process} inline reference.
	782	That is, all files in the `examples` folder are to be pretty-printed, except for `slow.lua`
	783	which is meant to be called from one of the examples. The see-reference to `testu.lua`
	784	resolves to 'examples/testu.lua.html'.
	785
	786	Examples may link back to the API documentation, for instance the example `input.lua` has a
	787	@\{spawn_process} inline reference.
568	788
569	789	## Readme files
570	790

572	792
573	793	readme = "readme.md"
574	794
575		This goes under the 'Topics' global section; the 'Contents' of this document is generated from the second-level (##) headings of the readme.
576
577		Readme files are always processed with Markdown, but may also contain @\{} references back to the documentation and to example files. Any symbols within backticks will be expanded as references, if possible. As with doc comments, a link to a standard Lua function like @\{os.execute} will work as well. Any code sections will be pretty-printed as Lua, unless the first indented line is '@plain'. (See the source for this readme to see how it's used.)
578
579		Another name for `readme` is `topics`, which is more descriptive. From LDoc 1.2, `readme/topics` can be a list of documents. These act as a top-level table-of-contents for your documentation. Currently, if you want them in a particular order, then use names like `01-introduction.md` etc which sort appropriately.
580
581		The first line of a document may be a Markdown `#` title. If so, then LDoc will regard the next level as the subheadings, normally second-level `##`. But if the title is already second-level, then third-level headings will be used `###`, and so forth. The implication is that the first heading must be top-level relative to the headings that follow, and must start at the first line.
582
583		A reference like @\{string.upper} is unambiguous, and will refer to the online Lua manual. In a project like Penlight, it can get tedious to have to write out fully qualified names like @\{pl.utils.printf}. The first simplification is to use the `package` field to resolve unknown references, which in this case is 'pl'. (Previously we discussed how `package` is used to tell LDoc where the base package is in cases where the module author wishes to remain vague, but it does double-duty here.) A further level of simplification comes from the @lookup directive in documents, which must start at the first column on its own line. For instance, if I am talking about `pl.utils`, then I can say "@lookup utils" and thereafter references like @\{printf} will resolve correctly.
584
585		Remember that the default is for references in backticks to be resolved; unlike @ references, it is not an error if the reference cannot be found.
586
587		The _sections_ of a document (the second-level headings) are also references. This particular section can be refered to as @\{doc.md.Resolving_References_in_Documents} - the rule is that any non-alphabetic character is replaced by an underscore.
	795	This goes under the 'Topics' global section; the 'Contents' of this document is generated
	796	from the second-level (##) headings of the readme.
	797
	798	Readme files are always processed with Markdown, but may also contain @\{} references back
	799	to the documentation and to example files. Any symbols within backticks will be expanded as
	800	references, if possible. As with doc comments, a link to a standard Lua function like
	801	@\{os.execute} will work as well. Any code sections will be pretty-printed as Lua, unless
	802	the first indented line is '@plain'. (See the source for this readme to see how it's used.)
	803
	804	Another name for `readme` is `topics`, which is more descriptive. From LDoc 1.2,
	805	`readme/topics` can be a list of documents. These act as a top-level table-of-contents for
	806	your documentation. Currently, if you want them in a particular order, then use names like
	807	`01-introduction.md` etc which sort appropriately.
	808
	809	The first line of a document may be a Markdown `#` title. If so, then LDoc will regard the
	810	next level as the subheadings, normally second-level `##`. But if the title is already
	811	second-level, then third-level headings will be used `###`, and so forth. The implication is
	812	that the first heading must be top-level relative to the headings that follow, and must
	813	start at the first line.
	814
	815	A reference like @\{string.upper} is unambiguous, and will refer to the online Lua manual.
	816	In a project like Penlight, it can get tedious to have to write out fully qualified names
	817	like @\{pl.utils.printf}. The first simplification is to use the `package` field to resolve
	818	unknown references, which in this case is 'pl'. (Previously we discussed how `package` is
	819	used to tell LDoc where the base package is in cases where the module author wishes to
	820	remain vague, but it does double-duty here.) A further level of simplification comes from
	821	the @lookup directive in documents, which must start at the first column on its own line.
	822	For instance, if I am talking about `pl.utils`, then I can say "@lookup utils" and
	823	thereafter references like @\{printf} will resolve correctly.
	824
	825	Remember that the default is for references in backticks to be resolved; unlike @
	826	references, it is not an error if the reference cannot be found.
	827
	828	The _sections_ of a document (the second-level headings) are also references. This
	829	particular section can be refered to as @\{doc.md.Resolving_References_in_Documents} - the
	830	rule is that any non-alphabetic character is replaced by an underscore.
588	831
589	832
590	833	## Tag Modifiers
591	834
592		New with this release is the idea of _tag modifiers_. For instance, you may say @\param[type=number] and this associates the modifier `type` with value `number` with this particular param tag. A shorthand can be introduced for this common case, which is "@tparam <type> <parmname> <comment>"; in the same way @\treturn is defined.
593
594		This is useful for larger projects where you want to provide the argument and return value types for your API, in a structured way that can be easily extracted later. There is a useful function for creating new tags that can be used in `config.ld`:
	835	Ay tag may have _tag modifiers_. For instance, you may say
	836	@\param[type=number] and this associates the modifier `type` with value `number` with this
	837	particular param tag. A shorthand can be introduced for this common case, which is "@tparam
	838	<type> <parmname> <comment>"; in the same way @\treturn is defined.
	839
	840	This is useful for larger projects where you want to provide the argument and return value
	841	types for your API, in a structured way that can be easily extracted later. There is a
	842	useful function for creating new tags that can be used in `config.ld`:
595	843
596	844	tparam_alias('string','string')
597	845
598	846	That is, "@string" will now have the same meaning as "@tparam string".
	847
	848	From 1.3, the following standard type aliases are predefined:
	849
	850	* `string`
	851	* `number`
	852	* `int`
	853	* `bool` Lua 'boolean' type
	854	* `func` 'function' (using 'function' would conflict with the type)
	855	* `tab` 'table'
	856	* `thread`
599	857
600	858	The exact form of `<type>` is not defined, but here is a suggested scheme:
601	859

607	865	{[string]=Bonzo,...} -- a map of Bonzo objects with string keys
608	866	Array(Bonzo) -- (assuming that Array is a container)
609	867
610		Currently the `type` modifier is the only one known and used by LDoc when generating HTML output. However, any other modifiers are allowed and are available for use with your own templates or for extraction by your own tools.
611
612		The `alias` function within configuration files has been extended so that alias tags can be defined as a tag plus a set of modifiers. So `tparam` is defined as:
	868	Currently the `type` modifier is the only one known and used by LDoc when generating HTML
	869	output. However, any other modifiers are allowed and are available for use with your own
	870	templates or for extraction by your own tools.
	871
	872	The `alias` function within configuration files has been extended so that alias tags can be
	873	defined as a tag plus a set of modifiers. So `tparam` is defined as:
613	874
614	875	alias('tparam',{'param',modifiers={type="$1"}})
615	876
	877	As an extension, you're allowed to use '@param' tags in table definitions. This makes it
	878	possible to use type alias like '@string' to describe fields, since they will expand to
	879	'param'.
	880
616	881	## Fields allowed in `config.ld`
617	882
618	883	These mostly have the same meaning as the corresponding parameters:
619	884
620		- `file` a file or directory containing sources. In `config.ld` this can also be a table of files and directories.
	885	- `file` a file or directory containing sources. In `config.ld` this can also be a table
	886	of files and directories.
621	887	- `project` name of project, used as title in top left
622	888	- `title` page title, default 'Reference'
623	889	- `package ` explicit base package name; also used for resolving references in documents

627	893	- `dir` directory for output files (default 'docs')
628	894	- `ext` extension for output (default 'html')
629	895	- `one` use a one-column layout
630		- `style`, `template` together these specify the directories for the style and and the template. In `config.ld` they may also be `true`, meaning use the same directory as the configuration file.
	896	- `style`, `template`: together these specify the directories for the style and and the
	897	template. In `config.ld` they may also be `true`, meaning use the same directory as the
	898	configuration file.
631	899
632	900	These only appear in `config.ld`:
633	901

636	904	- `readme` name of readme file (to be processed with Markdown)
637	905	- `no_return_or_parms` don't show parameters or return values in output
638	906	- `backtick_references` whether references in backticks will be resolved
639		- `manual_url` point to an alternative or local location for the Lua manual, e.g. 'file:///D:/dev/lua/projects/lua-5.1.4/doc/manual.html'
	907	- `manual_url` point to an alternative or local location for the Lua manual, e.g.
	908	'file:///D:/dev/lua/projects/lua-5.1.4/doc/manual.html'
640	909
641	910
642	911	Available functions are:
643	912
644		- `alias(a,tag)` provide an alias `a` for the tag `tag`, for instance `p` as short for `param`
645		- `add_language_extension(ext,lang)` here `lang` may be either 'c' or 'lua', and `ext` is an extension to be recognized as this language
	913	- `alias(a,tag)` provide an alias `a` for the tag `tag`, for instance `p` as short for
	914	`param`
	915	- `add_language_extension(ext,lang)` here `lang` may be either 'c' or 'lua', and `ext` is
	916	an extension to be recognized as this language
646	917	- `add_section`
647		- `new_type(tag,header,project_level)` used to add new tags, which are put in their own section `header`. They may be 'project level'.
648		- `tparam_alias(name,type)` for instance, you may wish that `string` means `@\tparam string`.
	918	- `new_type(tag,header,project_level)` used to add new tags, which are put in their own
	919	section `header`. They may be 'project level'.
	920	- `tparam_alias(name,type)` for instance, you may wish that `string` means `@\tparam
	921	string`.
649	922
650	923	## Annotations and Searching for Tags
651	924
652		Annotations are special tags that can be used to keep track of internal development status. The known annotations are 'todo', 'fixme' and 'warning'. They may occur in regular function/table doc comments, or on their own anywhere in the code.
	925	Annotations are special tags that can be used to keep track of internal development status.
	926	The known annotations are 'todo', 'fixme' and 'warning'. They may occur in regular
	927	function/table doc comments, or on their own anywhere in the code.
653	928
654	929	--- Testing annotations
655	930	-- @module annot1

663	938	--- @fixme what about else?
664	939	end
665	940
666		Although not currently rendered by the template as HTML, they can be extracted by the `--tags` command, which is given a comma-separated list of tags to list.
	941	Although not currently rendered by the template as HTML, they can be extracted by the
	942	`--tags` command, which is given a comma-separated list of tags to list.
667	943
668	944	@plain
669	945	D:\dev\lua\LDoc\tests> ldoc --tags todo,fixme annot1.lua

673	949
674	950	## Generating HTML
675	951
676		LDoc, like LuaDoc, generates output HTML using a template, in this case `ldoc_ltp.lua`. This is expanded by the powerful but simple preprocessor devised originally by [Rici Lake](http://lua-users.org/wiki/SlightlyLessSimpleLuaPreprocessor) which is now part of Penlight. There are two rules - any line starting with '#' is Lua code, which can also be embedded with '$(...)'.
	952	LDoc, like LuaDoc, generates output HTML using a template, in this case `ldoc_ltp.lua`. This
	953	is expanded by the powerful but simple preprocessor devised originally by [Rici
	954	Lake](http://lua-users.org/wiki/SlightlyLessSimpleLuaPreprocessor) which is now part of
	955	Penlight. There are two rules - any line starting with '#' is Lua code, which can also be
	956	embedded with '$(...)'.
677	957
678	958	<h2>Contents</h2>
679	959	<ul>

682	962	# end
683	963	</ul>
684	964
685		This is then styled with `ldoc.css`. Currently the template and stylesheet is very much based on LuaDoc, so the results are mostly equivalent; the main change that the template has been more generalized. The default location (indicated by '!') is the directory of `ldoc.lua`.
686
687		You may customize how you generate your documentation by specifying an alternative style sheet and/or template, which can be deployed with your project. The parameters are `--style` and `--template`, which give the directories where `ldoc.css` and `ldoc.ltp` are to be found. If `config.ld` contains these variables, they are interpreted slightly differently; if they are true, then it means 'use the same directory as config.ld'; otherwise they must be a valid directory relative to the ldoc invocation.
688
689		An example of fully customized documentation is `tests/example/style`: this is what you could call 'minimal Markdown style' where there is no attempt to tag things (except emphasizing parameter names). The narrative alone _can_ to be sufficient, if it is written appropriately.
690
691		Of course, there's no reason why LDoc must always generate HTML. `--ext` defines what output extension to use; this can also be set in the configuration file. So it's possible to write a template that converts LDoc output to LaTex, for instance. The separation of processing and presentation makes this kind of new application possible with LDoc.
	965	This is then styled with `ldoc.css`. Currently the template and stylesheet is very much
	966	based on LuaDoc, so the results are mostly equivalent; the main change that the template has
	967	been more generalized. The default location (indicated by '!') is the directory of `ldoc.lua`.
	968
	969	You may customize how you generate your documentation by specifying an alternative style
	970	sheet and/or template, which can be deployed with your project. The parameters are `--style`
	971	and `--template`, which give the directories where `ldoc.css` and `ldoc.ltp` are to be
	972	found. If `config.ld` contains these variables, they are interpreted slightly differently;
	973	if they are true, then it means 'use the same directory as config.ld'; otherwise they must
	974	be a valid directory relative to the ldoc invocation.
	975
	976	An example of fully customized documentation is `tests/example/style`: this is what you
	977	could call 'minimal Markdown style' where there is no attempt to tag things (except
	978	emphasizing parameter names). The narrative alone _can_ to be sufficient, if it is written
	979	appropriately.
	980
	981	Of course, there's no reason why LDoc must always generate HTML. `--ext` defines what output
	982	extension to use; this can also be set in the configuration file. So it's possible to write
	983	a template that converts LDoc output to LaTex, for instance. The separation of processing
	984	and presentation makes this kind of new application possible with LDoc.
692	985
693	986	## Internal Data Representation
694	987
695		The `--dump` flag gives a rough text output on the console. But there is a more customizeable way to process the output data generated by LDoc, using the `--filter` parameter. This is understood to be a fully qualified function (module + name). For example, try
	988	The `--dump` flag gives a rough text output on the console. But there is a more
	989	customizeable way to process the output data generated by LDoc, using the `--filter`
	990	parameter. This is understood to be a fully qualified function (module + name). For example,
	991	try
696	992
697	993	$ ldoc --filter pl.pretty.dump mylib.c
698	994
699		to see a raw dump of the data. (Simply using `dump` as the value here would be a shorthand for `pl.pretty.dump`.) This is potentially very powerful, since you may write arbitrary Lua code to extract the information you need from your project.
	995	to see a raw dump of the data. (Simply using `dump` as the value here would be a shorthand
	996	for `pl.pretty.dump`.) This is potentially very powerful, since you may write arbitrary Lua
	997	code to extract the information you need from your project.
700	998
701	999	For instance, a file `custom.lua` like this:
702	1000

713	1011	~/LDoc/tests/example$ ldoc --filter custom.filter mylib.c
714	1012	module mylib A sample C extension.
715	1013
716		The basic data structure is straightforward: it is an array of 'modules' (project-level entities, including scripts) which each contain an `item` array (functions, tables and so forth).
	1014	The basic data structure is straightforward: it is an array of 'modules' (project-level
	1015	entities, including scripts) which each contain an `item` array (functions, tables and so
	1016	forth).
717	1017
718	1018	For instance, to find all functions which don't have a @return tag:
719	1019

729	1029	end
730	1030	}
731	1031
732		The internal naming is not always so consistent; `ret` corresponds to @return, and `params` corresponds to @param. `item.params` is an array of the function parameters, in order; it is also a map from these names to the individual descriptions of the parameters.
733
734		`item.modifiers` is a table where the keys are the tags and the values are arrays of modifier tables. The standard tag aliases `tparam` and `treturn` attach a `type` modifier to their tags.
735
736
	1032	The internal naming is not always so consistent; `ret` corresponds to @return, and `params`
	1033	corresponds to @param. `item.params` is an array of the function parameters, in order; it
	1034	is also a map from these names to the individual descriptions of the parameters.
	1035
	1036	`item.modifiers` is a table where the keys are the tags and the values are arrays of
	1037	modifier tables. The standard tag aliases `tparam` and `treturn` attach a `type` modifier
	1038	to their tags.
	1039
	1040

+24

-9

readme.md less more

0	0	# LDoc - A Lua Documentation Tool
1	1
2		Copyright (C) 2011 Steve Donovan.
	2	Copyright (C) 2011-2012 Steve Donovan.
3	3
4	4	## Rationale
5	5
6		This project grew out of the documentation needs of [Penlight](https://github.com/stevedonovan/Penlight) (and not always getting satisfaction with LuaDoc) and depends on Penlight itself.(This allowed me to _not_ write a lot of code.)
	6	This project grew out of the documentation needs of
	7	[Penlight](https://github.com/stevedonovan/Penlight) (and not always getting satisfaction
	8	with LuaDoc) and depends on Penlight itself.(This allowed me to _not_ write a lot of code.)
7	9
8		The [API documentation](http://stevedonovan.github.com/Penlight/api/index.html) of Penlight is an example of a project using plain LuaDoc markup processed using LDoc.
	10	The [API documentation](http://stevedonovan.github.com/Penlight/api/index.html) of Penlight
	11	is an example of a project using plain LuaDoc markup processed using LDoc.
9	12
10		LDoc is intended to be compatible with [LuaDoc](http://luadoc.luaforge.net/manual.htm) and thus follows the pattern set by the various *Doc tools:
	13	LDoc is intended to be compatible with [LuaDoc](http://luadoc.luaforge.net/manual.htm) and
	14	thus follows the pattern set by the various *Doc tools:
11	15
12	16	--- Summary ends with a period.
13	17	-- Some description, can be over several lines.

18	22	function mod1.first_fun(p1,p2)
19	23	end
20	24
21		Tags such as `see` and `usage` are supported, and generally the names of functions and modules can be inferred from the code.
	25	Tags such as `see` and `usage` are supported, and generally the names of functions and
	26	modules can be inferred from the code.
22	27
23		LDoc is designed to give better diagnostics: if a `@see` reference cannot be found, then the line number of the reference is given. LDoc knows about modules which do not use `module()` - this is important since this function has become deprecated in Lua 5.2. And you can avoid having to embed HTML in commments by using Markdown.
	28	LDoc is designed to give better diagnostics: if a `@see` reference cannot be found, then the
	29	line number of the reference is given. LDoc knows about modules which do not use `module()`
	30	- this is important since this function has become deprecated in Lua 5.2. And you can avoid
	31	having to embed HTML in commments by using Markdown.
24	32
25	33	LDoc will also work with Lua C extension code, and provides some convenient shortcuts.
26	34
27		An example showing the support for named sections and 'classes' is the [Winapi documentation](http://stevedonovan.github.com/winapi/api.html); this is generated from [winapi.l.c](https://github.com/stevedonovan/winapi/blob/master/winapi.l.c).
	35	An example showing the support for named sections and 'classes' is the [Winapi
	36	documentation](http://stevedonovan.github.com/winapi/api.html); this is generated from
	37	[winapi.l.c](https://github.com/stevedonovan/winapi/blob/master/winapi.l.c).
28	38
29	39	## Installation
30	40
31		This is straightforward; the only external dependency is [Penlight](https://github.com/stevedonovan/Penlight), which in turn needs [LuaFileSystem](http://keplerproject.github.com/luafilesystem/). These are already present in Lua for Windows, and Penlight is also available through LuaRocks as `luarocks install penlight`.
	41	This is straightforward; the only external dependency is
	42	[Penlight](https://github.com/stevedonovan/Penlight), which in turn needs
	43	[LuaFileSystem](http://keplerproject.github.com/luafilesystem/). These are already present
	44	in Lua for Windows, and Penlight is also available through LuaRocks as `luarocks install
	45	penlight`.
32	46
33		Unpack the sources somewhere and make an alias to `ldoc.lua` on your path. That is, either an excutable script called 'ldoc' like so:
	47	Unpack the sources somewhere and make an alias to `ldoc.lua` on your path. That is, either
	48	an excutable script called 'ldoc' like so:
34	49
35	50	lua /path/to/ldoc/ldoc.lua $*
36	51