[FFmpeg-cvslog] Doxy style

[Måns Rullgård]

Stefano Sabatini <stefano.sabatini-lala at poste.it> writes:

> On date Sunday 2010-01-10 12:19:15 +0100, Diego Biurrun wrote:
>> On Fri, Jan 08, 2010 at 02:45:50AM +0100, Michael Niedermayer wrote:
>> > On Fri, Jan 08, 2010 at 01:42:22AM +0100, Diego Biurrun wrote:
>> > > On Fri, Jan 08, 2010 at 12:02:11AM +0100, Stefano Sabatini wrote:
>> > > > On date Thursday 2010-01-07 23:57:33 +0100, Diego Biurrun wrote:
>> > > > > On Thu, Jan 07, 2010 at 11:44:33PM +0100, stefano wrote:
>> > > > > > 
>> > > > > > Log:
>> > > > > > Fix doxy, use third person.
>> > > > > 
>> > > > > I made up my mind, I hate it.
>> > > > 
>> > > > That was discussed long time ago, and we decided to comply with
>> > > > JavaDoc recommendations.
>> > > 
>> > > I faintly remember something, but I never liked it in the first place.
>> > > 
>> > > I just compared POSIX docs and looked at a few random man pages.  The
>> > > former is completely written in nonpersonal form, the latter mostly.
>> > > 
>> > > > That said, if you want to convert each doxy
>> > > > to impersonal form I won't object - my only request is to keep it
>> > > > consistent - but that would be higly wasted time I think.
>> > > 
>> > > We have more doxy in non-third-person form than the other way around.
>> > > So the wasted time is being spent on making things less consistent
>> > > right now.  But let's leave this aside for now.
>> > > 
>> > > I've just asked around on IRC, a majority of native speakers agrees
>> > > with me.
>> > 
>> > A vote should be done on the ML and not exclude any developers
>> > my oppinon is that i prefer 3rd person 
>> 
>> We reach the point where the great unwashed[1] use voting to gang up on
>> experts[2].  It only took a few months to get to this point, congrats!
>> 
>> You'll have to find yourself another documentation maintainer.
>> I shall not be a part of this nonsense.
>
> Choosing third person vs impersonal form is just a convention problem,
> we adopted it following the JavaDoc recommendations, note that I asked
> you to make a choice many times without to get a response, then at
> some point you started a doxy clean-up using the third person, so I
> assumed that was the "official" style to follow.
>
> Then you as the doc maintainer can change the convention, possibly
> with a rationale (e.g. it is more grammatical correct, it is more
> clear, it is more "English") and documenting the choice in the
> guidelines, I don't think voting is needed for this, I'd even
> volunteer to convert the docs on some of the files on which I work.
>
> What is unacceptable is to change mind every few months, and then
> blaming others for just trying to follow a consistent style.

For the record, I hated third-person form all along, but since I never
read documentation, I didn't take much notice.

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