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

[Michael Niedermayer]

On Sun, Apr 19, 2009 at 03:20:06PM +0200, Vitor Sessak wrote:
> 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.

iam against non descriptive tag names like \p mixed into sentances

@returns the square root of arg

is rather readable, the tag forms an integral part of a valid english
sentance 

similarly, the tags in:
<code>
    for(i=0; i<8; i++)
        v+=i;
</code>

dont really hurt, they just waste 2 lines of space but then luckily
this is IIRC very uncommon in svn so it doesnt really matter either
way

but then

\p this and \p that change the \p variable to \p this.

is just unreadable and ugly
of course if all editors would be configured to show things like \p
in a color very close to the background then i suspect it would become
more readable but still ...

[...]

-- 
Michael     GnuPG fingerprint: 9FF2128B147EF6730BADF133611EC787040B0FAB

When you are offended at any man's fault, turn to yourself and study your
own failings. Then you will forget your anger. -- Epictetus
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
URL: <http://lists.mplayerhq.hu/pipermail/ffmpeg-devel/attachments/20090419/d666fa85/attachment.pgp>