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 gtk-doc tarball, doc/style-guide.txt)
  15 - GtkMisc and GtkFontSelectionDialog are example templates.
  16
  17 - in the arg clarification, use as much cross-reffing as possible.  Do it
  18   only where it is useful in the explanation text.
  19
  20 - examples
  21
  22   - use active form instead of imperative describing functions; we describe
  23     what the function does.
  24     good : creates a new buffer.
  25     bad : create new buffer
  26   - use singular for enum names; this makes it more natural to reference to
  27     it in the API docs
  28     good : GstBufferFlag
  29     bad : GstBufferFlags
  30   - in arg clarification, use a period and start with a small letter.
  31     Call the object you work on "a" instead of "the".  Call the other objects
  32     "the".
  33     If the object in question is the return value, this means you call the
  34     return value "a".  If the object in question is the first argument
  35     of the call, you call this argument "a" and the rest "the".
  36     good : @buf: a pointer to query.
  37     bad : @buf: The pointer to query