[PATCH v3 wayland 3/3] doc: generate doxygen html output from the scanner

[Peter Hutterer]

On Tue, Mar 01, 2016 at 06:21:17PM -0800, Bill Spitzak wrote:
> On Tue, Mar 1, 2016 at 2:21 PM, Peter Hutterer <peter.hutterer at who-t.net>
> 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