[FFmpeg-devel] [RFC] Should we use doxygen markup?

[Måns Rullgård]

Vitor Sessak <vitor1001 at gmail.com> writes:

> Stefano Sabatini wrote:
>> Hi,
>> as recently discussed.
>> Read for example:
>> http://thread.gmane.org/gmane.comp.video.ffmpeg.devel/88912/focus=88966
>> http://thread.gmane.org/gmane.comp.video.ffmpeg.devel/83525/focus=83592
>> Pros:
>> * improves doxygen (LaTeX/HTML) rendering.
>> * it may result more clear in some specific situation even for plain
>>   docs. For example:
>>   "reads the foo string \p string"
>>   vs
>>   "reads the foo string from string"
>>   helps to distinguish the use of a term for referring to a parameter
>>   rather to the generic meaning of its name.
>> Cons: * it may make plain docs less readable, and most people read
>> plain
>>   docs rather than autogenerated ones.
>> I'm biased towards keeping them, while Michael wants to remove them
>> all, what's certain is that we should try to keep a consistent style
>> in docs, so if we decide for removing them we should remove them
>> everywhere, or strive to use them (at least in new doxyies).
>> I'd like to hear what people think, especially from Diego.
>
> My opinion is to try to compromise between html and .c readability in
> a case by case basis. Personally, I'm against \p but I'm favorable to
> use things like \code.

I sometimes write the names of arguments in uppercase to distinguish
them from plain words.  It works fine if your actual code uses
lowercase as it should.

-- 
M?ns Rullg?rd
mans at mansr.com