On Tue, Mar 01, 2016 at 06:21:17PM -0800, Bill Spitzak wrote: > On Tue, Mar 1, 2016 at 2:21 PM, Peter Hutterer <[email protected]> > wrote: > > > On Tue, Mar 01, 2016 at 11:01:50AM -0800, Bill Spitzak wrote: > > > What exactly is this trying to solve? > > > > > > It seems entirely redundant with the protocol documentation. I think it > > > would be better to try to improve the protocol documentation, perhaps > > > inserting the C prototype as a one-line addition to each request and > > event > > > (as it is true that people are not so good at translating the protocol > > > description into exactly what they need to type into the program). I > > don't > > > like the idea that the same comment from the xml file will be repeated > > > three times in the docs. > > > > I'm looking forward to your patches. > > > > Okay, I'm actually surprised you think putting the C prototype in the > protocol docs is a good idea, but imho that is probably the best way to > deliver information that is missing now.
I don't necessarily think it's a good idea. I'm just waiting for your patches, so we can look at the result and analyze the idea/output then. hand-wavey comments are easy to write, patches are harder, useful patches harder still. but only one of these actually advances the project. > > I do think inserting the doxygen comments, as long as they are clean and > > > short, into the .h files is a good idea. C programmers are going to look > > > there. Please don't describe obvious arguments, or at least compress that > > > to a single line, and see if you can use per-enum-value comments rather > > > than repeating the entire enumeration. The main problem with the current > > > one is vertical size. > > > > > > However I would refrain from actually putting this Doxygen output into > > the > > > Wayland docs. The current output that you linked to is pretty horrific > > and > > > I would be ashamed to show it. > > > > I'm looking forward to your CSS styling attempts to change the default > > doxygen theme. Hint - you can get doxygen themes ready-made. Pick one that > > you don't consider horrific and send us patches, we'll review them provided > > they bikeshed is the right colour. > > > > It's not the theme, it's the arrangement into pages and the order of the > text in each page that bothers me. I think the current protocol > documentation is far closer to a useful arrangement. > > I have tried before to force Doxygen to produce chapters and sections (see > the abandoned fltk2.0 documentation for my results). It was a pretty much > losing battle. It may be best to produce a single giant page, or one page > per protocol, rather than this. I think the Doxygen comments in the header, > as long as they are information-dense (ie not too many Doxygen backslash > commands), are the main benifit of this, and that making the header file > prettier is currently better than trying to make the output prettier. again, looking forward to your patches. Cheers, Peter _______________________________________________ wayland-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/wayland-devel
