From a65affe9d04935207e3b52fdaa410367d2bd643e Mon Sep 17 00:00:00 2001 From: Julian Wollrath Date: Thu, 26 Feb 2015 12:09:17 +0100 Subject: [PATCH] Add section about LDoc in the contributing guide. --- docs/02-contributing.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/docs/02-contributing.md b/docs/02-contributing.md index 19856bbd..8a83f2d6 100644 --- a/docs/02-contributing.md +++ b/docs/02-contributing.md @@ -40,6 +40,39 @@ Imitate the existing code style. For concrete rules: A vim modeline is set in each file to respect this. +### Documentation of lua files + +For documentation purposes LDoc---see +[here](https://stevedonovan.github.io/ldoc/manual/doc.md.html) for its +documentation---is used. Comments, that shall be parsed by LDoc have the following format: + + --- summary. + -- Description; this can extend over + -- several lines + + ----------------- + -- This will also do. + + --[[-- + Summary. A description + ...; + ]] + +One can use the full power of [Markdown](http://daringfireball.net/projects/markdown) +with the extensions of [Discount](http://www.pell.portland.or.us/~orc/Code/discount/) +for mark-up in the comments. + +Every module and class should have a short description at its beginning which +should include `@author author`, `@copyright year author`, +`@release @AWESOME_VERSION@` and `@module module-name` or `@classmod class-name`. +Parameters of functions should be documented by `@param parameter description`, +return values via `@return description` or `@treturn type description`. For a +more comprehensive description of the available tags see the +[LDoc documentation](https://stevedonovan.github.io/ldoc/manual/doc.md.html). + +In addition to the regular tags provided by LDoc there are also some aliases for +tags defined in `docs/config.ld`. + ## Patches If you plan to submit patches, you should follow the following guidelines.