Add documentation

[Tieske]

I'd like to add inline documentation to the codebase, preferably using ldoc. Ldoc is pretty much the Lua standard for documentation.

I find the code pretty terse, so while going through it, it might be worthwhile to document my findings for future benefit of others.

[thibaultcha]

The thing is ldoc is mostly used to generate the HTML documentation of smaller projects, which we don't really need with Kong since we have the website and the developer documentation will consist of guides. We still document the code itself but since there is no point in generating the HTML, we do not bother with ldoc and adopted a more "free" but still descriptive format. It could still be converted to ldoc format tho, even if I doubt we will ever really use the generation part for Kong.

PS: if you have a clone of the repo from before last Friday, there was a history rewrite because of annoying binary files so you'll need a new clone.

[subnetmarco]

I think that we already use a format that's very similar to ldoc, so it may be worth it to just use ldoc even if we don't want to generate an HTML documentation (for example https://github.com/Mashape/kong/blob/master/kong/dao/cassandra/base_dao.lua#L61-L64).

[Tieske]

I'll include a basic ldoc config file (and exclude the generated docs from git) and then update the comments as I go along.