[FFmpeg-devel] [RFC] properly document av_crc

[Michael Niedermayer]

Hi

On Sun, Aug 19, 2007 at 02:30:09PM +0200, Reimar D?ffinger wrote:
[...]
> > [...]
> > > Index: libavutil/crc.c
> > > ===================================================================
> > > --- libavutil/crc.c	(revision 10141)
> > > +++ libavutil/crc.c	(working copy)
> > > @@ -37,6 +37,14 @@
> > >   * Inits a crc table.
> > >   * @param ctx must be an array of sizeof(AVCRC)*257 or sizeof(AVCRC)*1024
> > >   * @param cts_size size of ctx in bytes
> > > + * @param le if 1, lowest bit represents coefficient for highest exponent
> > > + *           of corresponding polynomial (both for poly and actual CRC).
> > 
> > > + *           If 0, you must swap the crc parameter and the result of av_crc
> > > + *           (can be simplified in most cases to e.g. bswap16):
> > > + *           bswap_32(crc << (32-bits))
> > 
> > its not really "must" its only needed if you need the crc in a non "bswaped"
> > format
> 
> Is
> "you must swap the crc parameter and the result of av_crc if you need
> the standard representation"
> better? I do understand when it is required to do and when not, but I
> don't know how to express it without pages of text ;-).

ok


> 
> > [...]
> > > @@ -70,6 +78,13 @@
> > >      return 0;
> > >  }
> > >  
> > > +/**
> > > + * Calculate the CRC of a block
> > > + * @param crc CRC of previous blocks if any or initial value for CRC.
> > > + * @return CRC updated with the data from the given block
> > > + *
> > > + * Please read the explanation of the le parameter to av_crc_init
> > 
> > i think theres a @see tag or so for this
> 
> I can do '@see av_crc_init() "le" parameter', but I have no idea what
> doxygen will make out of it, there is no documentation how to link to a
> specific function parameter, only to functions...

hmm, well choose whichever tag or lack of one you like most 

[...]
-- 
Michael     GnuPG fingerprint: 9FF2128B147EF6730BADF133611EC787040B0FAB

The educated differ from the uneducated as much as the living from the
dead. -- Aristotle 
-------------- 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/20070819/dc59aa2a/attachment.pgp>