From 76fc6b33063e67a9864becd2603514b1cc9e9218 Mon Sep 17 00:00:00 2001
From: Daniel Hahler <git@thequod.de>
Date: Sun, 14 Jun 2015 02:35:10 +0200
Subject: [PATCH] doc: LDoc config (version in desc); improve
 02-contributing.md

Adding @AWESOME_VERSION@ to the LDoc description is useful to have on
the index page.  While at it, it makes the description more
verbose/correct.

For docs/02-contributing.md, it lists the current aliases for typed
parameters, prefers/mentions `@tparam` and `@treturn` only, and fixes
some minor wording.

Closes #262.
---
 docs/02-contributing.md | 21 +++++++++++++--------
 docs/config.ld.in       |  6 +++---
 2 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/docs/02-contributing.md b/docs/02-contributing.md
index 077106b5..4043faa6 100644
--- a/docs/02-contributing.md
+++ b/docs/02-contributing.md
@@ -2,7 +2,7 @@
 
 ## Bugs
 
-Please look at `https://github.com/awesomeWM/awesome/issues`.
+Please look at [Github Issues](https://github.com/awesomeWM/awesome/issues).
 
 ## Style
 
@@ -39,7 +39,7 @@ Imitate the existing code style. For concrete rules:
 
 A vim modeline is set in each file to respect this.
 
-### Documentation of lua files
+### Documentation of Lua files
 
 For documentation purposes LDoc---see
 [here](https://stevedonovan.github.io/ldoc/manual/doc.md.html) for its
@@ -58,21 +58,26 @@ following format:
      ...;
     ]]
 
-One can use the full power of
+You 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
+[Discount](http://www.pell.portland.or.us/~orc/Code/discount/) for markup 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
+
+Parameters of functions should be documented using
+`@tparam <type> <parmname> <description>`, and return values via
+`@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`.
+for typed parameters defined in `docs/config.ld`, e.g. `@client` for
+`@tparam client.client`, `@tag` for `@tparam tag` and `@tab` for
+`@tparam table`).
 
 ## Patches
 
diff --git a/docs/config.ld.in b/docs/config.ld.in
index d1d49d55..707b99d1 100644
--- a/docs/config.ld.in
+++ b/docs/config.ld.in
@@ -2,7 +2,7 @@
 
 project='awesome'
 title='awesome API documentation'
-description='highly configurable X window manager'
+description='API documentation for awesome, a highly configurable X window manager (version @AWESOME_VERSION@).'
 
 -- More on it: https://github.com/stevedonovan/LDoc/blob/master/doc/doc.md#markdown-support
 format='discount'
@@ -13,7 +13,7 @@ pretty='lua'
 style="!pale"
 backtick_references=true
 merge=true
-use_markdown_titles = true
+use_markdown_titles=true
 wrap=true
 topics={
     '00-authors.md',
@@ -28,7 +28,7 @@ tparam_alias('tag', 'tag')
 tparam_alias('tab', 'table')
 
 -- More fitting section names
-kind_names={topic='Documentation',module='Libraries'}
+kind_names={topic='Documentation', module='Libraries'}
 
 -- Sort modules alphabetically
 sort_modules=true