gstreamer/docs/random/thomasvs/docreview

38 lines
1.3 KiB
Text
Raw Normal View History

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