From: Thomas V. S. <tho...@us...> - 2002-08-30 16:03:00
|
CVS Root: /cvsroot/gstreamer Module: gstreamer Changes by: thomasvs Date: Fri Aug 30 2002 09:02:57 PDT Log message: some hint updates Modified files: docs/random/thomasvs: docreview Links: http://cvs.sf.net/cgi-bin/viewcvs.cgi/gstreamer/gstreamer/docs/random/thomasvs/docreview.diff?r1=1.1&r2=1.2 ====Begin Diffs==== Index: docreview =================================================================== RCS file: /cvsroot/gstreamer/gstreamer/docs/random/thomasvs/docreview,v retrieving revision 1.1 retrieving revision 1.2 diff -u -d -r1.1 -r1.2 --- docreview 17 Apr 2002 12:29:25 -0000 1.1 +++ docreview 30 Aug 2002 16:02:45 -0000 1.2 @@ -11,6 +11,9 @@ * 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 @@ - 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 |