| 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 |