Codebase list lua-ldoc / 2bd0c3f
Getting all the sections in a more beginner's friendly, logical order JonasT 10 years ago
1 changed file(s) with 72 addition(s) and 30 deletion(s). Raw diff Collapse all Expand all
+72
-30
doc/doc.md less more
3131
3232 ## Commenting Conventions
3333
34 LDoc follows the conventions established by Javadoc and later by LuaDoc.
34 LDoc follows the conventions established by Javadoc and later by LuaDoc to document the
35 modules, functions, types (=classes) and so forth of your API.
36
37 ### Doc comments
3538
3639 Only 'doc comments' are parsed; these can be started with at least 3 hyphens, or by a empty
3740 comment line with at least 3 hypens:
5457 warning issued. The only exception is if the module starts with an explicit `module`
5558 statement.
5659
60
61 ### Summary and tags of a doc comment
62
5763 All doc comments start with a summary sentence, that ends with a period or a question mark.
5864 An optional description may follow. Normally the summary sentence will appear in the module
5965 contents.
6066
6167 After this descriptive text, there will typically be _tags_. These follow the convention
6268 established by Javadoc and widely used in tools for other languages.
69
70 The first important tag to know is the module tag:
71
72 ### The module tag, naming and describing your API module
73
74 The first thing in your API module should be a name and a description.
75 This is how a module is commonly done in Lua 5.2 with a @module tag at the top
76 which introduces the name:
77
78 --- a test module
79 -- @module test
80
81 local test = {}
82
83 function test.my_module_function_1()
84 ...
85 end
86
87 ...
88
89 return test
90
91 This sets up a module named 'test' with the description 'a test module'.
92
93 ### Describing functions with tags:
94
95 The next thing to describe are the functions your module has.
96 This is a simple example of a documented function:
6397
6498 --- foo explodes text.
6599 -- It is a specialized splitting operation on a string.
69103 ....
70104 end
71105
72 There are also 'tparam' and 'treturn' which let you [specify a type](#Tag_Modifiers):
73
74 -- @tparam string text the string
106 The tags basically add all the detail that cannot be derived from the source code
107 automatically.
108
109 ### Most common tags
110
111 Common tags are the 'param' tag which takes a parameter name followed by a parameter
112 description separated by a space, and the 'return' tag which is simply followed by
113 a description for a return value:
114
115 -- @param name_of_parameter the description of this parameter as verbose text
116 -- @return the description of the return value
117
118 If you want to [specify a type](#Tag_Modifiers) for a parameter or a return value,
119 there are also 'tparam' and 'treturn':
120
121 -- @tparam string text this parameter is named 'text' and has the fixed type 'string'
75122 -- @treturn {string,...} a table of substrings
76123
77124 There may be multiple 'param' tags, which should document each formal parameter of the
78125 function. For Lua, there can also be multiple 'return' tags
79
80 --- solvers for common equations.
81 module("solvers", package.seeall)
82126
83127 --- solve a quadratic equation.
84128 -- @param a first coeff
98142 end
99143
100144 ...
101
102 This is the common module style used in Lua 5.1, but it's increasingly common to see less
103 'magic' ways of creating modules in Lua. Since `module` is deprecated in Lua 5.2, any
104 future-proof documentation tool needs to handle these styles gracefully:
105
106 --- a test module
107 -- @module test
108
109 local test = {}
110
111 --- first test.
112 function test.one()
113 ...
114 end
115
116 ...
117
118 return test
119
120 Here the name of the module is explicitly given using the 'module' tag. If you leave this
121 out, then LDoc will infer the name of the module from the name of the file and its relative
122 location in the filesystem; this logic is also used for the `module(...)` idiom. (How this
123 works and when you need to provide extra information is discussed later.)
145 Of course there is also the 'module' tag which you have already seen.
146
147 As an alternative to using the 'module' tag as described before, you
148 can still start your modules the Lua 5.1 way:
149
150 --- solvers for common equations.
151 module("solvers", package.seeall)
152
153 However, the 'module' function is deprecated in Lua 5.2 and it is increasingly
154 common to see less 'magic' ways of creating modules, as seen in the description
155 of the 'module' tag previously with the explicitely returned module table.
156
157 ### Local module name
124158
125159 It is common to use a local name for a module when declaring its contents. In this case the
126160 'alias' tag can tell LDoc that these functions do belong to the module:
148182 --- second test.
149183 M.two = function(...) ... end
150184
185 ### Local functions
186
151187 Apart from exported functions, a module usually contains local functions. By default, LDoc
152188 does not include these in the documentation, but they can be enabled using the `--all` flag.
153189 They can be documented just like 'public' functions:
160196 --- we need to give a hint here for foo
161197 -- @local here
162198 function foo(...) .. end
199
200 ### Tables and other constant values
163201
164202 Modules can of course export tables and other values. The classic way to document a table
165203 looks like this:
204242 occur once in a comment. The basic rule is that a single doc comment can only document one
205243 entity.
206244
245 ### Alternative way of specifying tags
246
207247 Since 1.3, LDoc allows the use of _colons_ instead of @.
208248
209249 --- a simple function.
218258 In this style, types may be used directly if prefixed with '!' or '?' (for type-or-nil)
219259
220260 (see @{colon.lua}, rendered [here](http://stevedonovan.github.io/ldoc/examples/colon))
261
262 ### Which files are processed
221263
222264 By default, LDoc will process any file ending in '.lua' or '.luadoc' in a specified
223265 directory; you may point it to a single file as well. A 'project' usually consists of many