[FFmpeg-devel] [VOTE] 1st/3rd person doxy

Benoit Fouet benoit.fouet
Fri Jul 9 12:13:57 CEST 2010


Hi,

On Fri, 09 Jul 2010 10:47:31 +0100 M?ns Rullg?rd wrote:
> Rob <robert.swain at gmail.com> writes:
> 
> > 2010/7/9 M?ns Rullg?rd <mans at mansr.com>:
> >> Mike Melanson <mike at multimedia.cx> writes:
> >>
> >>> What's wrong with the de facto policy of everyone adds documentation
> >>> as best they can and the native speakers clean it up after the fact?
> >>
> >> What a wonderful idea.
> >
> > I think we have some non-native speakers amongst us who are very good
> > at English, better even than a lot of native speakers.
> 
> So s/native/proficient/.
> 
> > My stance on documentation is that I don't really care if it's
> > perfect, or perfectly consistent. If it's comprehensible then it's
> > good. If people want to make it perfect and perfectly consistent,
> > fine.
> 
> Incorrect grammar is hard to parse and detracts from the meaning of
> the statement.  Anyone who wants to improve the English form of
> the documentation should be encouraged to do so.
> 

As Stefano already stated, this is not (really) a grammar problem.

As far as '1st/3rd person doxy' is concerned, my personal preference
(that I have not raised before) would be for the way it is today.
The patch Stefano proposed to add this policy to the doc also looked OK.

So I guess this is choice 5 of this pole.

Now, the 'real' issue is to be able to define a level of triviality
above which one should be able to commit a change/correction to the
documentation so that it is not controversial. I guess that'd depend on
the maintainer of the modified file, and possibly on the committer too.
For non-trivial commits, a patch should be sent and reviewed prior to
being commited.

That was, of course, only my two cents. But since this discussion is
lasting, I guessed that the more opinions, the better.

Ben



More information about the ffmpeg-devel mailing list