[PATCH 00/21] Documentation improvements

[Jason Ekstrand]

Matthias,
First, I want to reiterate my thanks for working on this.  There's a
lot that could use some filling in.  In general, I think you're doing
a great job.  There are a lot of little consistency things that you're
fixing as well as grammar problems etc.

That said, I think I'm done reading your changes for now. At this
point, I find myself mostly making the same comments over and over
again.  So, instead of going through it line-by-line, I'll make my
comments in one place here and wait for the second version.

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.

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.

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!
--Jason Ekstrand

On Sat, Mar 30, 2013 at 3:42 PM, Jason Ekstrand <jason at jlekstrand.net> wrote:
> Matthias,
> Thanks for working on this!  My brief reading indicates that you've
> done a pretty good job over-all.  I'm going throgh your patches now
> and so you can expect patch-by-patch comments shortyly.
> --Jason Ekstrand
>
> On Sat, Mar 30, 2013 at 12:11 AM,  <matthias.clasen at gmail.com> wrote:
>> From: Matthias Clasen <mclasen at redhat.com>
>>
>> Hi, I spent some time going over the documentation, trying
>> to fill gaps in my understanding - and in the documentation.
>>
>> Here are the resulting patches.
>>
>> Matthias Clasen (21):
>>   docs: Reorder some sections
>>   docs: Slight rewording
>>   docs: Improve the 'Types of Compositors' section
>>   docs: Improve the 'Connect time' section
>>   doc: Improve various sections of the documentation
>>   docs: Consistency fixes
>>   docs: Improve wl_display protocol docs
>>   docs: Improve the wl_registry protocol docs
>>   docs: Improve wl_callback protocol docs
>>   docs: Improve wl_shm and wl_shm_pool protocol docs
>>   docs: Improve the wl_data_* procol docs
>>   docs: Improve wl_shell/wl_shell_surface docs
>>   docs: Improve wl_surface protocol docs
>>   docs: Improve the wl_seat protocol docs
>>   docs: Improve wl_pointer protocol docs
>>   docs: Improve wl_keyboard protocol docs
>>   docs: Improve wl_touch protocol docs
>>   docs: Improve the wl_output protocol docs
>>   docs: Improve wl_region protocol docs
>>   docs: Add details about surfaces
>>   docs: Add details about grabs
>>
>>  doc/Wayland/en_US/Compositors.xml | 119 +++---
>>  doc/Wayland/en_US/Protocol.xml    | 108 +++---
>>  doc/Wayland/en_US/Wayland.xml     |   4 +-
>>  protocol/wayland.xml              | 768 +++++++++++++++++++++++++-------------
>>  4 files changed, 598 insertions(+), 401 deletions(-)
>>
>> --
>> 1.8.1.4
>>
>> _______________________________________________
>> wayland-devel mailing list
>> wayland-devel at lists.freedesktop.org
>> http://lists.freedesktop.org/mailman/listinfo/wayland-devel