[PATCH 00/21] Documentation improvements

[Jason Ekstrand]

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.

On Sat, Mar 30, 2013 at 11:47 PM, Matthias Clasen
<matthias.clasen at gmail.com> wrote:
> On Sat, Mar 30, 2013 at 6:32 PM, Jason Ekstrand <jason at jlekstrand.net> wrote
>
>>
>> 1. I said this in one of the e-mails, but avoid unneeded
>> documentation.  The documentation as is is fairly sparse and needs to
>> be filled in.  However, too much documentation can sometimes be a bad
>> thing too.  For example, on events called "destroy" it's pretty
>> obvious what it does: It destroys the object.  Adding a comment really
>> doesn't help and just makes for more to wade through.  Also, you have
>> a lot of "the serial of the X event" comments.  Again, these don't
>> really add anything.  If there is something special or noteworthy
>> about the serial argument on a particular event, go ahead and document
>> it.
>
> No doubt, there can be too much verbiage in docs.
>
> But I don't think the wayland protocol docs are even close the point
> of 'too much documentation'. And since the spec that needs to be
> precise enough to guarantee interoperatibility, you shouldn't assume
> that anything is obvious. Your example proves the point: an event does
> not do anything, it just informs you about something. You thought it
> was obvious and got it wrong...

No, I didn't get it wrong, I made a (rather unfortunate) typo above in
that I said "destroy event" when I should have said "destroy request".
 Given the current topic, that typo is, admittedly, inexcusable.  I
actually do have a fairly good handle on the wayland protocol as I
have personally implemented a non-trivial portion of it in Java for my
wayland android stuff.  That said, yes, the protocol is
underdocumented.

Concerning the serial arguments, I'm going to go back on what I said.
Thinking about it more, I do think it's good to be precise about
exactly what serial is being referred to.  I may suggest different
wording, but I think the precision is good.

>> 2. There are several places where you add a one-line summary at the
>> beginning of the documentation block.  This is what the summary tag is
>> for.  Having it as a single line at the top of the block as well will
>> simply make people more confused.  Particularly if the wayland XML is
>> used go generate comments that are to be parsed by something like
>> doxygen or javadoc.  That said, fixing capitalization in the summaries
>> wouldn't be bad.
>
> 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.

Summaries:
Each <documentation> tag can have a corresponding "summary" attribute.
 Personally, I think of the summaries the same way I think of the
first line of a javadoc comment or @brief in doxygen (which I will
refer to as @brief from now on).  In those two, you usually write a
@brief such as "Requests a frame callback event" and then in the body
of the documentation you describe in detail how that works.  Looking
more carefully at some JavaDoc stuff, sometimes the summary is
repeated as the main documentation comment.  However, this is not
always the case.  If the more detailed description is enough, I don't
think we need to have a "double summary" if it doesn't add anything.

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.

I thought there were more style issues I came across... I guess not.
I'm open to discussion on the above, I just think it would be good to
figure out what style we want before we make it a particular one.

Thanks,
--Jason Ekstrand