[FFmpeg-devel] [PATCH] WMA Voice decoder

Stefano Sabatini stefano.sabatini-lala
Fri Jan 22 01:08:13 CET 2010


On date Thursday 2010-01-21 13:30:03 +0000, M?ns Rullg?rd encoded:
> Michael Niedermayer <michaelni at gmx.at> writes:
> 
> > On Thu, Jan 21, 2010 at 02:06:10PM +0100, Michael Niedermayer wrote:
> >> On Thu, Jan 21, 2010 at 12:16:40PM +0000, M?ns Rullg?rd wrote:
> >> > Michael Niedermayer <michaelni at gmx.at> writes:
> >> > 
> >> > > On Thu, Jan 21, 2010 at 11:43:00AM +0000, M?ns Rullg?rd wrote:
> >> > >> Stefano Sabatini <stefano.sabatini-lala at poste.it> writes:
> >> > >> 
> >> > >> > On date Wednesday 2010-01-20 16:56:25 -0500, Ronald S. Bultje encoded:
> >> > >> > [...]
> >> > >> >> +/**
> >> > >> >> + * Initialize decoder.
> >> > >> >> + */
> >> > >> > [...]
> >> > >> >
> >> > >> > Just a note on the doxy, please use third person,
> >> > >> 
> >> > >> Please don't.  It looks weird to me, and I've never seen any other
> >> > >
> >> > > so does you pink bike look to me ;)
> >> > >
> >> > >> documentation do it.  It's time we stopped this madness.
> >> > >
> >> > > java*
> >> > 
> >> > FFmpeg is not written in java.
> >> 
> >> thats a straw man argument :)
> >> 
> >> "I've never seen any other documentation do it"
> >> "java"
> >> "FFmpeg is not written in java"
> >> 
> >> we could continue this along the lines of
> >> "But ffmpeg is written C"
> >> "C is a progamming language"
> >> ...
> >> 
> >> this misses the original point though that you tried to argue 3rd person
> >> was uncommon and you had not seen it, i do think its quite common and
> >> actually standard in some areas like javadocs which syntax we use as well
> 
> I haven't read any javadoc since they introduced that rule,
> apparently.

This doesn't surprise me, as you yourself alleged many times that you
never read docs ;-).
> 
> > That said, i do think the worst is to waste time to change easy
> > understandable comments to a different grammer style and i think we
> > dont really disagree on this?
> 
> There we agree.

Just to stay in theme of useless wastes of time, I did a quick audit
on the API docs adopted by other projects, some examples here:

http://www.videolan.org/developers/vlc/doc/doxygen/html/vlc__acl_8h.html
http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer-libs/html/GstBaseSrc.html
http://api.jquery.com/category/selectors/
http://sofia-sip.sourceforge.net/refdocs/su/su__wait_8h.html#8386ed97e8ea59d71625968185aed3f9
http://java.sun.com/j2se/1.4.2/docs/api/java/lang/Object.html
http://www.docs.hp.com/en/B2355-60130/gethostent.3N.html

Note that FFmpeg is not worse than most of the projects I checked, you
can easily find in the same page third person, impersonal form, simple
future all mixed up in randomic ways.

Java at least got one thing correct, the documentation looks
consistent (third person, they wrote the javadoc recommends afterall).

The classical style (adopted for example by most manual references I
checked) is:
This function sets the color of the bikeshed to color.

so the natural compaction seems to me:
Sets the color of the bikeshed to color.

Patch attached for some missing function doxies in opt.h.

Regards.
-- 
FFmpeg = Faboulous and Frightening Mortal Powerful Ecletic God
-------------- next part --------------
A non-text attachment was scrubbed...
Name: document-the-fucked-opt-h.patch
Type: text/x-diff
Size: 2280 bytes
Desc: not available
URL: <http://lists.mplayerhq.hu/pipermail/ffmpeg-devel/attachments/20100122/c4429fb4/attachment.patch>



More information about the ffmpeg-devel mailing list