Just a quick follow up.

On 22/05/14 06:29, Uli Schlachter wrote:
> The only thing that I saw so far that I didn't like is the @alias client in
> lib/awful/client.lua.in. The client docs are in luadoc/client.lua.in.

What did you mean by alias? What LDoc provides is aliases for param
types (I can set them in config.ld.in). So the alias `@client` expands
to `@tparam client` and LDoc automatically finds the class and links to it.

Do you mean that writing plain `@tparam client` would be better.

Also, since v1.3 LDoc provides some aliases [1] for built-in types, such
as `@string`, `@tab` and so on. Do you think it's a better idea to use
the aliases instead of `@tparam string` and `@tparam table`?

> However somewhere in Flyspray there is an issue about merging that with the C
> code and have LDoc generate the docs from there. Having the code with the docs
> makes it less likely that someone forgets to update them when changing the 
> code.
> Since you are now my local LDoc expert, could you spent 10 minutes to look 
> into
> how feasible this is and then just tell me "sorry, we should stay with the 
> fake
> lua files for documenting the C API".

I looked into it a bit more and I realised that this bit might not be as
straight forward. I am not as familiar with the C side of awesome and I
realised that at least the client module functions are spread across
several files. So I will need to spend a bit more time to look into this.

Hence, I think the best way to approach it would be to first fix the LUA
documentation and then do the C API next as a separate PR. I do think
that transferring the docs to the C code has to be done, but as a
separate PR.



[1]: http://stevedonovan.github.io/ldoc/manual/doc.md.html#Tag_Modifiers

To unsubscribe, send mail to awesome-devel-unsubscr...@naquadah.org.

Reply via email to