On Mon, Apr 1, 2013 at 10:43 AM, Jason Ekstrand <ja...@jlekstrand.net> wrote: > 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.
No worries, I didn't take it personally. Stylistic editing and patch review are not easy to marry. On some level, it would be best if krh just did an editing pass and committed a version of the docs that he is happy with. I was hoping my patches could serve as a basis for that. >> >> 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. Interesting. I didn't know that there are other consumers than what's in the wayland repo. > > 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. Yeah, what annoyed me about the @ was that it doesn't do anything, is inconsistently used, and makes it into the formatted document. I had thought about using <function> markup, or some other suitable docbook tag. It does create some nicer output. But I didn't want to disrupt the text with too much markup. So far, it is really nicely readable even in the xml. _______________________________________________ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel