[FFmpeg-devel] [PATCH] change AC3 to AC-3

[Justin Ruggles]

Diego Biurrun wrote:
> On Tue, Aug 05, 2008 at 07:03:28PM -0400, Justin Ruggles wrote:
>> The Wanderer wrote:
>>> Justin Ruggles wrote:
>>>
>>>> Diego Biurrun wrote:
>>>>
>>>>> On Sun, Aug 03, 2008 at 12:07:06PM -0400, Justin Ruggles wrote:
>>>>>> Well let me go on record as an objector then. :)
>>>>> What alternative do you suggest?
>>>> I'm not saying that this is what I always follow... but if I had to
>>>> choose a set of rules...
>>>>
>>>> I think that a period should be used for either indicating the end of
>>>> a complete sentence or separating a Doxygen brief description from a
>>>> detailed description.  For capitalization, I think that the only
>>>> considerations should be normal English grammer: start of a sentence,
>>>> proper names, acronyms, etc...
>>> If I'm not mistaken, that's roughly the same as the current rule. The
>>> only question I see is, how do you define what counts as a "sentence"?
>>>
>>> Diego has, I believe, been using the definition that a sentence must
>>> have both a verb and an object, and anything which has both is one. This
>>> seems reasonable to me; it sometimes produces results which I do not
>>> find intuitive, but it has not to date produced results which I found
>>> seriously objectionable. Do you disagree with that definition? If so,
>>> what would you propose as an alternative?
>> Yes, that is exactly where I object.  I think that a sentence fragment
>> should not be treated as a complete sentence.  To me it seems more than
>> just counter-intuitive.
> 
> Where did I say that a sentence fragment should be treated as a
> sentence?  If I did, that surely was not my intention.
> 
> In any case sentence fragments used in longer blocks of text are an
> indication of bad style.  Avoiding them is almost always an improvement.
> 
>> That said, I don't think it's something that should be strictly
>> enforced.  Either way should be acceptable, and should not be subject to
>> review, the same way general coding style is not subject to review
>> unless it is drammatically inconsistent or ugly.
> 
> You asked for a review, you got one...

I only submitted the patch because there were 2 files in there that are
not maintained by me.  I was trying to understand the logic behind your
review, which was not clear to me, so I asked...

> This is not strictly enforced and I do not change it in files I review,
> if it is handled in a more or less consistent fashion (which most of the
> time, it is not).  However, when it comes to Doxygen documentation, then
> I believe we should strive for a general consistent style across all
> files.

Ok. I think we're on the same page then.

I agree with you that Doxygen documentation should be as consistent as
possible.  Some simple examples would probably be helpful, or even a
statement such as "Format your Doxygen comments like it is done in
avcodec.h."

-Justin