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.cla...@gmail.com> wrote: > On Sat, Mar 30, 2013 at 6:32 PM, Jason Ekstrand <ja...@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 _______________________________________________ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
