[FFmpeg-devel] [PATCH 1/2] Prettify eval.h doxy.

[Stefano Sabatini]

On date Thursday 2010-06-03 01:32:47 +0200, Michael Niedermayer encoded:
> On Thu, Jun 03, 2010 at 12:35:21AM +0200, Stefano Sabatini wrote:
> > On date Wednesday 2010-06-02 00:44:34 +0200, Stefano Sabatini encoded:
> > > On date Tuesday 2010-06-01 21:43:50 +0200, Michael Niedermayer encoded:
> > > > On Tue, Jun 01, 2010 at 06:45:06PM +0200, Stefano Sabatini wrote:
> > [...]
> > > > > give clear
> > > > > indications and I'll try to follow them, while trying to avoid overly
> > > > > long lines at the same time.
> > > > 
> > > > with 1 line "things" the fact that each line is one "thing" provides
> > > > adequate seperation
> > > > with multiline "things" another form of seperation is needed or this becomes
> > > > a bit spagethi like.
> > > > the empty space in the first columns helps a bit but i think
> > > > that maybe empty lines would help more
> > > 
> > > As you may guess I'm also concerned about the consistency with the
> > > rest of the doxies, I don't want to end up with each file showing a
> > > different style, so while I can tolerate long lines and vertical
> > > @param alignment I'd prefer to avoid other forms of separation between
> > > params seen nowhere else in the docs.
> > > 
> > > Anyway, since I don't want to waste more time on this, feel free to
> > > fetch the patch, edit and apply it yourself, or just give me the OK
> > > and I'll apply it as it is.
> > 
> > Another version of the bikeshed attached, that should hopefully make
> > both Michael and me happy.
> > 
> > I'll apply the patch in few days unless there are other comments.
> 
> its still a unreadable spaethi mess, so i object
> add empty lines of dont put a @param over more than 1 line

* overly long lines are unreadable, as they force you to move your focus

* the problem with separating each @param with an empty line, is that:
  1. is inconsistent with the rest of the doxies

  2. it tends to increase the lenght of the doxy, in this case it
     happens that for some of the functions the doxy would not be
     anymore contained in a single page, which is detrimental to
     readability

* I believe that 4-chars indentation is already providing a good
  enough separation between the different @params

Regards.
-- 
FFmpeg = Fanciful Fabulous Mind-dumbing Programmable Elastic Gorilla