thanks and introduction

[Bryce Harrington]

On Wed, Mar 09, 2016 at 08:53:20AM -0800, Yong Bakos wrote:
> > On Mar 9, 2016, at 2:16 AM, Pekka Paalanen <ppaalanen at gmail.com> wrote:
> > 
> > The simple-* demos are self-contained code wise, almost all the other
> > demos build upon the "toytoolkit" (window.c/h) which supports a lot more
> > features.
> > 
> > One more example worth mentioning is weston-info.c, which is an
> > independent tool that prints out the protocol interfaces supported by
> > any compositor (not just weston), and some more details on the
> > interfaces it knows about.
> 
> Thanks Pekka and Bryce,
> I'm digging into the simple-* demos.
> 
> 
> > On Mar 7, 2016, at 11:43 AM, Bryce Harrington <bryce at osg.samsung.com> wrote:
> > In particular we lack much depth in
> > introductory guides, so as you go through your learning curve, maybe
> > take notes and consider making tutorials or other "getting started" type
> > materials.
> 
> I'm working on distilling my notes into a doc. Need to verify their
> correctness again on a fresh vm. I'll also try to distill these steps
> into something usable in wayland-build-tools.
> 
> 
> > If you run 'make check' on wayland you'll notice a bunch
> > of warnings about missing documentation.  The missing parameter
> > documentation should be extremely simple to add.
> 
> So, just to verify, grep'ing make check for "not documented" shows a lot
> of structs, struct members, macro defs, and entire functions that lack
> documentation. I don't see any (I believe) warnings about just missing
> parameters.

What I'm referring to are warnings that look like:

/home/bryce/src/Wayland/wayland/wayland-1.10.90/_build/protocol/wayland-server-protocol.h:3082: warning: The following parameters of wl_keyboard_send_key(struct wl_resource *resource_, uint32_t serial, uint32_t time, uint32_t key, uint32_t state) are not documented:
  parameter 'serial'
  parameter 'key'
  parameter 'state'

etc.

But yeah, structs, macros, and functions are missing documentation as
well.  My thinking here though is that a lot of the parameters are
trivially easy to document.  Often you can (and should) just copy the
text from other places where the parameter is already documented.

> As this is my first contribution I just want to make sure I
> get things right. My output:
> 
> https://gist.github.com/ybakos/acd582a6001013df11e6
> 
> Are all "not documented" elements fair game, or is there
> something that deserves higher priority?  Maybe point out one specific
> line in that output just so it's clear to me.

Anything that was critical has probably already been documented.

The wl_array and wl_list classes would probably be easy jump-in points
since they are relatively basic types with few dependencies elsewhere on
the code, and they're used pervasively.  Also, you'd probably need to
understand those in order to document some of the other classes.

Bryce