diff --git a/doc/doc.md b/doc/doc.md index 3248c2e..f5e8280 100644 --- a/doc/doc.md +++ b/doc/doc.md @@ -32,7 +32,10 @@ end-users to build your documentation using this simple command. ## Commenting Conventions -LDoc follows the conventions established by Javadoc and later by LuaDoc. +LDoc follows the conventions established by Javadoc and later by LuaDoc to document the +modules, functions, types (=classes) and so forth of your API. + +### Doc comments 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: @@ -55,6 +58,9 @@ Any module or script must start with a doc comment; any other files are ignored warning issued. The only exception is if the module starts with an explicit `module` statement. + +### Summary and tags of a doc comment + 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. @@ -62,6 +68,34 @@ contents. After this descriptive text, there will typically be _tags_. These follow the convention established by Javadoc and widely used in tools for other languages. +The first important tag to know is the module tag: + +### The module tag, naming and describing your API module + +The first thing in your API module should be a name and a description. +This is how a module is commonly done in Lua 5.2 with a @module tag at the top +which introduces the name: + + --- a test module + -- @module test + + local test = {} + + function test.my_module_function_1() + ... + end + + ... + + return test + +This sets up a module named 'test' with the description 'a test module'. + +### Describing functions with tags: + +The next thing to describe are the functions your module has. +This is a simple example of a documented function: + --- foo explodes text. -- It is a specialized splitting operation on a string. -- @param text the string @@ -70,17 +104,27 @@ established by Javadoc and widely used in tools for other languages. .... end -There are also 'tparam' and 'treturn' which let you [specify a type](#Tag_Modifiers): +The tags basically add all the detail that cannot be derived from the source code +automatically. - -- @tparam string text the string +### Most common tags + +Common tags are the 'param' tag which takes a parameter name followed by a parameter +description separated by a space, and the 'return' tag which is simply followed by +a description for a return value: + + -- @param name_of_parameter the description of this parameter as verbose text + -- @return the description of the return value + +If you want to [specify a type](#Tag_Modifiers) for a parameter or a return value, +there are also 'tparam' and 'treturn': + + -- @tparam string text this parameter is named 'text' and has the fixed type 'string' -- @treturn {string,...} a table of substrings There may be multiple 'param' tags, which should document each formal parameter of the function. For Lua, there can also be multiple 'return' tags - --- solvers for common equations. - module("solvers", package.seeall) - --- solve a quadratic equation. -- @param a first coeff -- @param b second coeff @@ -99,29 +143,19 @@ function. For Lua, there can also be multiple 'return' tags end ... +Of course there is also the 'module' tag which you have already seen. -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: +As an alternative to using the 'module' tag as described before, you +can still start your modules the Lua 5.1 way: - --- a test module - -- @module test + --- solvers for common equations. + module("solvers", package.seeall) - local test = {} +However, the 'module' function is deprecated in Lua 5.2 and it is increasingly +common to see less 'magic' ways of creating modules, as seen in the description +of the 'module' tag previously with the explicitely returned module table. - --- first test. - function test.one() - ... - end - - ... - - return test - -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.) +### Local module name 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: @@ -149,6 +183,8 @@ explicit assignment to a variable: --- second test. M.two = function(...) ... end +### Local functions + 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: @@ -162,6 +198,8 @@ They can be documented just like 'public' functions: -- @local here function foo(...) .. end +### Tables and other constant values + Modules can of course export tables and other values. The classic way to document a table looks like this: @@ -205,6 +243,8 @@ and 'return' can be specified multiple times, whereas a type tag like 'function' occur once in a comment. The basic rule is that a single doc comment can only document one entity. +### Alternative way of specifying tags + Since 1.3, LDoc allows the use of _colons_ instead of @. --- a simple function. @@ -220,6 +260,8 @@ In this style, types may be used directly if prefixed with '!' or '?' (for type- (see @{colon.lua}, rendered [here](http://stevedonovan.github.io/ldoc/examples/colon)) +### Which files are processed + 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