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

[Stefano Sabatini]

On date Friday 2010-06-04 00:40:58 +0200, Michael Niedermayer encoded:
> On Fri, Jun 04, 2010 at 12:33:14AM +0200, Stefano Sabatini wrote:
> > 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
> 
> i disagree

Well since we can't find an agreement, I'm dropping the patch as I
want to spend my time on more useful stuff.

Regards.
-- 
FFmpeg = Formidable and Faithless Multimedia Problematic Epic Geek