[FFmpeg-devel] [VOTE] 1st/3rd person doxy
Fri Jul 9 12:28:11 CEST 2010
Stefano Sabatini <stefano.sabatini-lala at poste.it> writes:
> On date Friday 2010-07-09 10:46:52 +0200, Vladimir Pantelic encoded:
>> Mike Melanson wrote:
>> >On 07/08/2010 06:43 PM, Michael Niedermayer wrote:
>> >> 5. add a 1st person perogative rule to policy
>> >Spelled "prerogative", believe it or not.
>> >> also there are 2 contradicting viewpoints, first being that it should be
>> >> decided by our best english speakers and the second is that everyone
>> >> has to work with the documentation and thus should decide.
>> >> also theres the question if we need/want another rule or not
>> >What's wrong with the de facto policy of everyone adds documentation as
>> >best they can and the native speakers clean it up after the fact?
>> which makes it proposal 7) and I vote for it
> I don't consider this a valid solution. Problem is that is not clear
> at all who should be considered an "English expert", as it is not
> possible to clearly define who is a "C language expert".
I am both. Settled.
> Also the question is controversial enough so there is not a clearly
> correct solution, I believe it's much about conventions and not about
> clearly defined/definable argumentations, the same reason for which
> someone might prefer:
> foo = 42;
> rather than:
> foo= 42;
While I thoroughly despise the latter form, I don't insist on Michael
reverting any commits using it. It's his code, and he's the one most
likely to read it again.
Documentation is different. It is written primarily for _others_ to
read, and following a comprehensible style should be of obvious
> Indeed this is a question of *style* rather than of grammar:
That's one man's misguided opinion. We don't even know how well he
> I vote for the impersonal form, as it's the form currently implemented
> in FFmpeg, looks easier to write and seems it's the favored form by
> many FFmpeg devs (Diego, Mans, Ronald, Alex). I may change idea if
> someone can show technical argumentations (for example quoting the
> position of an English professor).
I have another argument for the impersonal/prescriptive/imperative
form: it is the form used by dictionaries, and an API reference is
comparable to a dictionary.
> If the issue is voted and the result will be against it, I won't mind
> at all, but please let's stop to fight about the number of angels
> contained in the tip of a needle.
Obviously, we need to vote on that too.
mans at mansr.com
More information about the ffmpeg-devel