[FFmpeg-cvslog] r21073 - trunk/libavfilter/avfilter.h

Michael Niedermayer michaelni
Sun Jan 10 18:02:40 CET 2010


On Sun, Jan 10, 2010 at 12:19:15PM +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!

I would assume that sun who is behind the javadoc guidelines has no lack of
native english speakers and even professional experts.
And still its 3rd person they recommand.

A Function in C does something, that is it might perform some computation on
its arguments and return the result.

[sqrt(x)] returns the square root of x.

How else would you awnser the question
What does sqrt(x) do?


> 
> You'll have to find yourself another documentation maintainer.
> I shall not be a part of this nonsense.

The doxygen comments are maintained by the maintainers of the respective
files as they and people working on the code are the ones qualified to write
such code documentation.
There is no need for the general documentation maintainer to like the doxygen
style because he isnt doing anything with them anyway. Its important that the
actual people who work with the code can understand and write the comments.
This is not end user documentation.
In that sense i see no need to exclude people from a vote, this isnt about
what native english speakers prefer but rather what the c developers working
with the code prefer.

[...]

-- 
Michael     GnuPG fingerprint: 9FF2128B147EF6730BADF133611EC787040B0FAB

If you think the mosad wants you dead since a long time then you are either
wrong or dead since a long time.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
URL: <http://lists.mplayerhq.hu/pipermail/ffmpeg-cvslog/attachments/20100110/e7c20cef/attachment.pgp>



More information about the ffmpeg-cvslog mailing list