[PATCH] MPEG doxy comments (was Re: [Ffmpeg-devel] Motion Estimation in snow.c for Waevelet encoded frames (DWT))

[Guillaume POIRIER]

Hi,

On 3/31/07, Michael Niedermayer <michaelni at gmx.at> wrote:
> Hi
>
> On Sat, Mar 31, 2007 at 11:06:45PM +0200, Guillaume POIRIER wrote:
> > Hi,
> > [..]
> >
> > I've put your explanations as Doxy comments.
> >
> > Is it worth making it to svn?
>
> definitly, see my comments below though
> [...]
> >      int pre_penalty_factor;
> > -    int penalty_factor;
> > +    int penalty_factor;                /*!< an estimate of the bits required to
> > +                                        code a given mv value, e.g. (1,0) takes
> > +                                        more bits than (0,0). We have to
> > +                                        estimate whether any reduction in
> > +                                        residual is worth the extra bits. */
>
> maybe clarify mv value vs. difference to predited mv ...

Sure, no problem, but you'd have to provide me this explanation. I
don't know the different between both :-)


> [...]
> > Index: libavcodec/motion_est_template.c
> > ===================================================================
> > --- libavcodec/motion_est_template.c  (revision 8578)
> > +++ libavcodec/motion_est_template.c  (working copy)
> > @@ -991,13 +991,24 @@
> >          return   var_diamond_search(s, best, dmin, src_index, ref_index, penalty_factor, size, h, flags);
> >  }
> >
> > +/**
> > +   \param P[10][2] a list of candidate mvs to check before starting the
> > +   iterative search. If one of the candidates is close to the optimal mv, then
> > +   it takes fewer iterations. And it increases the chance that we find the
> > +   optimal mv.
> > + */
> >  static av_always_inline int epzs_motion_search_internal(MpegEncContext * s, int *mx_ptr, int *my_ptr,
> >                               int P[10][2], int src_index, int ref_index, int16_t (*last_mv)[2],
> >                               int ref_mv_scale, int flags, int size, int h)
> >  {
> >      MotionEstContext * const c= &s->me;
> > -    int best[2]={0, 0};
> > -    int d, dmin;
> > +    int best[2]={0, 0};      /*!< x and y coordinates of the motion vector.
>
> of the best motion vector IIRC

Ok, fixed


> > +                               i.e. the difference between the position of the
> > +                               block current being encoded and the position of
> > +                            the block chosen to predict it from. */
> > +    int d;                   ///< the score (cmp + penalty) of any given mv
> > +    int dmin;                /*!< the best value of d, i.e. the score
> > +                               corresponding to the mv stored in best[]. */
>
>
> can local variables be doxygenized?

I actually don't know. I had a quick look at Doxygen doc and it's
doesn't seem to tell it clearly. I guess it just doesn't hurt to
doxygen in a Doxy-compatible manner.

> also please use consistent doxygen tags (/*! vs. /**)

Fixed in my local copy.

Guillaume

-- 
Rich, you're forgetting one thing here: *everybody* except you is
stupid.
    M?ns Rullg?rd