[FFmpeg-devel] [VOTE] 1st/3rd person doxy
Fri Jul 9 12:13:57 CEST 2010
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
That was, of course, only my two cents. But since this discussion is
lasting, I guessed that the more opinions, the better.
More information about the ffmpeg-devel