[FFmpeg-devel] [VOTE] 1st/3rd person doxy

[Måns Rullgård]

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

> Indeed this is a question of *style* rather than of grammar:
> http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#styleguide

That's one man's misguided opinion.  We don't even know how well he
spoke English.

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

-- 
M?ns Rullg?rd
mans at mansr.com