Documentation cross-reference (Re: [RFC] wl_surface scale and crop protocol extension)

[Pekka Paalanen]

On Fri, 3 May 2013 19:16:41 +0100
Daniel Stone <daniel at fooishbar.org> wrote:

> On 3 May 2013 18:50, Bill Spitzak <spitzak at gmail.com> wrote:

> > Currently one of the things you can do to a wl_surface is that you can find
> > the wl_shell object and ask it to create a wl_shell_surface object given a
> > wl_surface id, and then you can do things to this wl_shell_surface object.
> > However this is not listed under wl_surface, instead it is listed under two
> > other sections with no links to them (there are backward links but that is
> > pretty useless): wl_shell and wl_shell_surface. I think this is extremely
> > confusing and was probably one of the biggest obstacles I had trying to
> > figure wayland out.
> >
> > What I would like to see is that under wl_surface you see a section that
> > says something like "wl_scaler:". Listed under that are the methods that are
> > currently listed under wl_surface_scaler. The title "wl_scaler:" implies all
> > this information: the actual calling convention is to find the global
> > wl_scaler object, call a method called get_scaler_surface with the
> > wl_surface id, and that returns a new object called a wl_scaler_surface, and
> > you call the listed methods on *this* object. The documentation is now where
> > a user can find it, and a lot of boilerplate is elided.
> >
> > One thing that would help a lot is for there to be a standard as to whether
> > a wl_foo global object, when asked to create an object for a wl_bar object,
> > that the object is called wl_foo_bar and not wl_bar_foo. Currently the
> > wl_shell and wl_scaler disagree about this. Since wl_shell_surface is in
> > much more than wl_surface_scaler use I recommend standardizing on putting
> > the global object's type first.
> 
> OK, so it pretty much looks like just cosmetic/documentation changes -
> none of which I'm against at all.  Obviously we can't break existing
> protocol though (such as renaming wl_shell_surface to
> wl_surface_shell), but we can improve the documentation.  I'm sure
> patches for that would be gratefully accepted.

How about automatically generating a cross-reference list for each
object class, which would contain every request and event that has
this object class as an argument (and make those links to the
corresponding doc)?

This would be for the html/pdf docs. Now, who would implement that...


Thanks,
pq