[FFmpeg-cvslog] r11225 - trunk/libavformat/avformat.h

[Diego Biurrun]

On Mon, Dec 17, 2007 at 02:38:19AM +0100, Michael Niedermayer wrote:
> On Sun, Dec 16, 2007 at 11:40:05PM +0000, M?ns Rullg?rd wrote:
> > Diego Biurrun <diego at biurrun.de> writes:
> > 
> > > On Sun, Dec 16, 2007 at 10:52:23PM +0000, M?ns Rullg?rd wrote:
> > >> Michael Niedermayer <michaelni at gmx.at> writes:
> > >> 
> > >> > On Sun, Dec 16, 2007 at 06:22:09PM +0100, Diego Biurrun wrote:
> > >> >> On Sat, Dec 15, 2007 at 05:54:59PM +0100, michael wrote:
> > >> >> > 
> > >> >> > Log:
> > >> >> > document how to free the result of av_alloc_format_context()
> > >> >> > 
> > >> >> > --- trunk/libavformat/avformat.h	(original)
> > >> >> > +++ trunk/libavformat/avformat.h	Sat Dec 15 17:54:58 2007
> > >> >> > @@ -569,7 +569,11 @@ int av_open_input_file(AVFormatContext *
> > >> >> > +/**
> > >> >> > + * Allocate an AVFormatContext.
> > >> >> > + * can be freed with av_free() but dont forget to free everything you
> > >> >> > + * explicitly allocated as well!
> > >> >> 
> > >> >> Could you please make an effort to avoid obvious misspellings ("dont")?
> > >> >> It took some work to fix these things up in FFmpeg and it would be a
> > >> >> pity to let it go to waste again.
> > >> >
> > >> > feel free to improve the precommit check script
> > >> 
> > >> I have to say, this attitude of yours is starting to get quite tiresome.
> > >
> > > Very much so.  I don't understand why you are such a complete perfectionist
> > > about what code is acceptable for FFmpeg and at the same time disregard
> > > the quality of the (Doxygen) documentation.
> 
> because "dont" is as readable with as well as without some little speck
> between n and t, buggy, slow, bloated, ... code though has a quite noticeable
> effect, take a look at our bugtracker how many bugs are there about spelling
> and grammer and how many are there about other things

There have been numerous (as in infinite) complaints about lack of FFmpeg
documentation, both developer docs and user docs.

"Dont" may be as readable to you as "do not" and maybe it is to others
that have gotten used to reading your prose, but it sure does not extend
to the general case.  Especially not to people with poor English skill.
Unfortunately most readers are not native speakers and have to struggle
quite a bit to understand even good written English.

Nevertheless - wantonly - refusing to punctuate is not something that
does not affect readability.  Leaving out periods and commas turns your
prose into a hard-to-decipher mess.  Believe me, I read your stuff, I
have often enough struggled with it.  If this is your preferred way of
writing emails, well, I won't be able to reform you.  But if you write
Doxygen comments etc. this way, then you damage their comprehensibility.

> i prefer to concentrate on fixing things which do matter to our developers and
> users, over things which dont
> and belive it or not reading everything twice to fix spelling capitalization
> and all that takes time, time i could spent fixing some issues

It also takes me time to doublecheck my commits, time I could spend
fixing other issues.  Diligence always takes time, but it's worth it.

I can claim with some confidence that I can write English at near native
levels yet I always reread any documentation I write two or three times
to make sure it's correct and understandable.

So how much time are we talking about and what percentage of the time
you take to write Doxygen documentation would it take to expand a
condensed "dont" into "do not"?  We are talking about typing two more
characters.  This is not asking much.

However, the main problem I have is the attitude you are telegraphing by
refusing to give in on this issue.  "I do whatever damn well I want and
consider right; I don't give a damn what others think about the issue."

I do not expect you to become a perfect writer, much less overnight, but
I would sure appreciate if at least the things that get pointed out to
you - and are easy to fix with little effort - would get some attention.
After all writing documentation *is* part of coding and writing good
documentation *does* make you a better coder.

It's also not conducive to a good and productive team atmosphere if you
ignore what the others think and want.  Everybody should give in a
little for the common good.

> also ive a suggestion, ill be more carefull with my spelling and you fix
> a few issues on our bugtracker (and no i dont mean closing invalid ones but
> real bugfixes which require a change of the C code)
> i think that would be fair, it would require each of us to do something
> we dont commonly do

Does that apply to me or Mans?

Diego