[PATCH 00/21] Documentation improvements

[Matthias Clasen]

On Mon, Apr 1, 2013 at 10:43 AM, Jason Ekstrand <jason at jlekstrand.net> wrote:
> Matthias,
> First, I would like to apologize for a) being a bit harsh and
> overbearing in my comments and b) getting too caught up in stylistic
> issues.  I really should have read through it for content first and
> just kept a tally for style things.  At some point here (probably not
> till at least the weekend) I will try to go through and do a thorough
> content-only review of the wayland.xml changes.  I will leave the
> style discussion here and we can figure out how we want to handle each
> of these issues in one place.  Disagreements about style really
> shouldn't be handled inline anyway.

No worries, I didn't take it personally. Stylistic editing and patch
review are not easy to marry. On some level, it would be best if krh
just did an editing pass and committed a version of the docs that he
is happy with. I was hoping my patches could serve as a basis for
that.


>>
>> For judging formatting questions like this, I recommend proof-reading
>> the generated docs. That's what I looked at when making those changes.
>
> Allow me to explain my perspective on this a bit more.  I am not only
> looking at the HTML generated by publican (as given on the webpage)
> but my own XML protocol parser that I have written to dump out Java
> classes for wayland-java generates JavaDoc comments for each
> event/request/interface as per the XML documentation flags.  I also
> think it would be a good idea to, at some point, make the C scanner
> dump out doxygen comments.  Later this week I'll try to get publican
> installed so I can understand the documentation pipeline a bit better.

Interesting. I didn't know that there are other consumers than what's
in the wayland repo.


>
> References to arguments or events/requests:
> One thing Matthias pulled out was some "@" characters before arguments
> or event/request names.  I agree that the "@" isn't really doing
> anything for us.  That said, I'm not sure we just want to get rid of
> it.  It would be nice if we had something some sort of flag that
> publican could turn into <function> and other things could turn into
> whatever type of reference it requires.  I realize going through and
> adding that would be a lot of work.  Some times this can be easily
> fixed by simply moving pieces of the doc comment to argument comments.

Yeah, what annoyed me about the @ was that it doesn't do anything, is
inconsistently used, and makes it into the formatted document. I had
thought about using <function> markup, or some other suitable docbook
tag. It does create some nicer output. But I didn't want to disrupt
the text with too much markup. So far, it is really nicely readable
even in the xml.