[FFmpeg-cvslog] r23822 - in trunk: ffserver.c libavformat/avformat.h libavformat/gopher.c libavformat/http.c libavformat/internal.h libavformat/mmst.c libavformat/rtmpproto.c libavformat/rtpproto.c libavformat/rts...

[Stefano Sabatini]

On date Monday 2010-06-28 23:04:13 +0200, Diego Biurrun wrote:
> On Sun, Jun 27, 2010 at 11:30:09PM +0200, Stefano Sabatini wrote:
> > On date Sunday 2010-06-27 16:16:46 +0200, mru wrote:
> > 
> > > --- trunk/libavformat/avformat.h	Sun Jun 27 14:21:12 2010	(r23821)
> > > +++ trunk/libavformat/avformat.h	Sun Jun 27 16:16:46 2010	(r23822)
> > > @@ -1185,6 +1185,32 @@ int64_t av_gen_search(AVFormatContext *s
> > >  int av_set_parameters(AVFormatContext *s, AVFormatParameters *ap);
> > >  
> > >  /**
> > > + * Split a URL string into components.
> > 
> > This is also changing the verbal form used, making it inconsistent
> > with the sanctioned style (yes again the stupid
> > impersonal-vs-third-person-form-holy-bikeshed).
> 
> That sure was one clever plot.  You and Michael ganged up on me and
> Mans with the help of Java conventions.  I thought for a moment we knew
> more English than you and had all Unix man pages, the POSIX specs and
> most of the C environment to back us up.

I'll reply now and I promise to myself to not reply again, we all have
more useful things to do than argue on which verbal form is The
Correct One.

* Javadoc uses and recommends the third person
* Javadoc spec writers are supposedly English native speakers, and/or
  possibly they consulted some English expert
* "Javadoc" contains the name of a popular programming language, but
  that doesn't mean that it can't be used for documenting the API for
  other languages, and indeed it is widely used for that purpose
* FFmpeg adopts javadoc/doxygen for its API documentation
* we should better stick to already existing conventions rather than
  hack up another variant of them (as it was discussed long time ago
  for the documentation style)
* there is no evidence that the impersonal form is *soo much* better
  than the third person, indeed you yourself Diego, at some time
  adopted the third person as the official style
* saying that "we're more English speaker than you so we know better
  despite any argumentation you may produce" is not a valid argument
* saying "you ganged up on us to impose your choice", while on the
  contrary I always strived to produce argumentations, is unfair and
  impolite, and is not a valid argument
* even in the case there is an evidence that using FOO rather than BAR
  is better, we should also consider the cost involved in the change
  (that is the update of all the docs written so far, maybe the same
  time could be spent better, for example by adding content)
* if you think that it is so important to prefer the impersonal form
  over the third person, I don't (and I *never* did) oppose to that
  change, provided that we're going to ship a *consistent* style for
  all the docs
* my point is always been about consistency rather than about the
  preference of FOO over BAR, on which I never had a strong opinion.

Regards.