gstreamer/docs/random/thomasvs/docreview

Documentation review

* gstbuffer
- What are the flags in GstBuffer ? used anywhere ? defined how ?


* General
- how can we define common terms and make them cros-ref'd ?
  e.g. timestamps in buffer, do we say everywhere that they're in nanosec ?


* Style
- when in doubt, try to conform to GTK+ reference docs
  (in the gtk-doc tarball, doc/style-guide.txt)
- GtkMisc and GtkFontSelectionDialog are example templates.

- in the arg clarification, use as much cross-reffing as possible.  Do it
  only where it is useful in the explanation text.

- examples

  - use active form instead of imperative describing functions; we describe
    what the function does.
    good : creates a new buffer.
    bad : create new buffer
  - use singular for enum names; this makes it more natural to reference to
    it in the API docs
    good : GstBufferFlag
    bad : GstBufferFlags
  - in arg clarification, use a period and start with a small letter.
    Call the object you work on "a" instead of "the".  Call the other objects
    "the".
    If the object in question is the return value, this means you call the
    return value "a".  If the object in question is the first argument
    of the call, you call this argument "a" and the rest "the".
    good : @buf: a pointer to query.
    bad : @buf: The pointer to query