docs/random/thomasvs/docreview

   1 Documentation review
   2
   3 * gstbuffer
   4 - What are the flags in GstBuffer ? used anywhere ? defined how ?
   5
   6
   7 * General
   8 - how can we define common terms and make them cros-ref'd ?
   9   e.g. timestamps in buffer, do we say everywhere that they're in nanosec ?
  10
  11
  12 * Style
  13 - when in doubt, try to conform to GTK+ reference docs
  14 - in the arg clarification, use as much cross-reffing as possible.  Do it
  15   only where it is useful in the explanation text.
  16
  17 - examples
  18
  19   - use active form instead of imperative describing functions; we describe
  20     what the function does.
  21     good : creates a new buffer
  22     bad : create new buffer
  23   - use singular for enum names; this makes it more natural to reference to
  24     it in the API docs
  25     good : GstBufferFlag
  26     bad : GstBufferFlags