Hi Ignas,

sorry for not replying earlier, but I don't have much time. So what follows is
just from a really quick look.

On 19.05.2014 14:29, Ignas Anikevicius wrote:
> Hello everybody,
> I am playing with LDoc at the moment to convert Awesome docs to use
> markdown instead plain text/HTML mixture.

Thanks a lot for looking into this. And you already seem to know more LDoc
tricks than I ever did. Nice!

> I made a pull request on github as I thought it may be more flexible to
> comment code than the mailing list, but let me know if you think
> otherwise. So this is an early WIP, but since this is a big project and
> the documentation style is something to be decided by the whole
> community, I wanted to post it early rather than making very big changes
> later on.

So far the community is just you. I guess since you are doing the work, you also
get to decide how you want to do your work.

> At the moment I have only ported the awful.rules module and started with
> a few others. The generated documentation can be found on:
> http://gns-ank.github.io/awesome/doc/index.html
> The PR on github is on:
> https://github.com/awesomeWM/awesome/pull/37

That looks nice and better than what we have so far.

No idea where to put it, but could you also write a short "how to document"
tutorial? Something that points to the right parts of the LDoc documentation and
adds some awesome-specifics. Perhaps some examples since I am confused about the
@client[opt] that I am staring at right now, but it is easily understandable and
obviously means an optional client parameter.

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.

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".

> Cheers,
> Ignas

Many, many thanks for looking into this area that was previously relatively
neglected. Sorry for neglecting it.

- He made himself, me nothing, you nothing out of the dust
- Er machte sich mir nichts, dir nichts aus dem Staub

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

Reply via email to