[PATCH 00/21] Documentation improvements

[Matthias Clasen]

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

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

> I have a few more general comments at the tops of the reply e-mails I
> sent out.  Keeping all this in mind, I'd like you to go back through
> and make a second version.  Looks good so far!

Sure. It might be a while before I find another chunk of time to sink
into this, though.


Thanks for the review