some hint updates

Original commit message from CVS:
some hint updates

docs/random/thomasvs/docreview

@@ -11,6 +11,9 @@ Documentation review
 
 * 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.
 
@@ -18,9 +21,17 @@ Documentation review
 
   - use active form instead of imperative describing functions; we describe
     what the function does.
-    good : creates a new buffer
+    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