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

[Stefano Sabatini]

On date Friday 2009-06-19 10:20:59 +0200, Reimar D?ffinger encoded:
> 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?
> 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
> 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 believe the doxygen comment is just a *description* of what the
function does, rather than an expansion of the name of the function,
and we have nothing like a distinction between brief description and
long description, having that semantic distinction would be a quite
insane idea imo.

Also consider these:

* javadoc specs recommend the third person form, and we're trying to
  adhere to that rather than reinvent our own style

* this is also the predominant style in the FFmpeg code, and
  consistency is a nice thing to achieve

Regards.
-- 
FFmpeg = Foolish and Fostering Mind-dumbing Peaceless Encoding/decoding Ghost