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

Måns Rullgård mans
Sun Apr 19 15:48:00 CEST 2009

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

More information about the ffmpeg-devel mailing list