[FFmpeg-devel] [PATCH]Basic XSUB encoder (take 5)

[Michael Niedermayer]

On Fri, Jun 19, 2009 at 10:20:59AM +0200, Reimar D?ffinger wrote:
> On Thu, Jun 18, 2009 at 11:59:42PM +0200, Stefano Sabatini wrote:
> > On date Saturday 2009-05-23 23:03:31 +0200, Reimar D?ffinger encoded:
> > [...]
> > > Index: libavcodec/xsubenc.c
> > > ===================================================================
> > > --- libavcodec/xsubenc.c	(revision 0)
> > > +++ libavcodec/xsubenc.c	(revision 0)
> > [...]
> > > +/**
> > > + * Encode a single color run. At most 16 bits will be used.
> > > + * \param len length of the run, values > 255 mean "until end of line", may not be < 0.
> > > + * \param color color to encode, only the lowest two bits are used and all others must be 0.
> > > + */
> > 
> > Encodes.
> 
> Is that commonly accepted as the correct way to write it?

i tend to advocate its use, and was (and probably is) in the official
javadoc docs from sun, that is they also recommand 3rd person ...
and doxygen uses javadoc syntax ...
it always seemed to me that we should follow these things unless we
have a good reason not to, consistency accross projects ...
then again ive no strong feelings about it and am perfectily fine
if you prefer some other form in files you maintain ...


> AFAICT at least all comments I wrote use this form.
> Why? Because the "Encodes" probably is supposed to stand for
> "this function encodes", but this is not how I see it, a function
> does not do anything but is only a description, instead the brief

I tend to consider verbs like "encode" to be the "doing something"
kind, if encoding is not doing something then what else is it?
A cup of encode? :)


> description is an expansion of the function name, i.e.
> put_xsub_rle(...);
> is a compilable short-hand for
> "Encode a single color run."

i tend to see the doxy as an awnser to the question
"what does this function do"
-> (it) "Encodes a single color run"

also theres the difference between
a function does
a variable is

[...]

-- 
Michael     GnuPG fingerprint: 9FF2128B147EF6730BADF133611EC787040B0FAB

There will always be a question for which you do not know the correct awnser.
-------------- 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-devel/attachments/20090619/2a6f6441/attachment.pgp>