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 <ja...@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.cla...@gmail.com> wrote: >> From: Matthias Clasen <mcla...@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@lists.freedesktop.org >> http://lists.freedesktop.org/mailman/listinfo/wayland-devel _______________________________________________ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
