[SCM] libav/experimental: State in the guidelines that function and parameter descriptions in the doxy must use impersonal verbal form.

siretart at users.alioth.debian.org siretart at users.alioth.debian.org
Sun Jun 30 17:10:15 UTC 2013


The following commit has been merged in the experimental branch:
commit 0e7fa0bc3ba8eaea3eb623aa269806d2eca3a2c2
Author: Stefano Sabatini <stefano.sabatini-lala at poste.it>
Date:   Sat Jul 3 18:19:38 2010 +0000

    State in the guidelines that function and parameter descriptions in
    the doxy must use impersonal verbal form.
    
    This form is apparently favored by most English speaker developers,
    and has the advantage of being easier to use than the third person
    form.
    
    This should hopefully put an end to the Third Person Holy Bikeshed
    War.
    
    Originally committed as revision 24023 to svn://svn.ffmpeg.org/ffmpeg/trunk

diff --git a/doc/developer.texi b/doc/developer.texi
index edce7ea..c816352 100644
--- a/doc/developer.texi
+++ b/doc/developer.texi
@@ -83,6 +83,9 @@ format (see examples below) so that code documentation
 can be generated automatically. All nontrivial functions should have a comment
 above them explaining what the function does, even if it is just one sentence.
 All structures and their member variables should be documented, too.
+Impersonal form must be used for the function and parameter
+descriptions, e.g. "Set the bikeshed color." is favored over "Sets the
+bikeshed color.".
 @example
 /**
  * @@file mpeg.c

-- 
Libav/FFmpeg packaging



More information about the pkg-multimedia-commits mailing list