mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-05 16:06:43 +00:00
8cfb8350b8
Original commit message from CVS: some hint updates
37 lines
1.3 KiB
Text
37 lines
1.3 KiB
Text
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
|