[FFmpeg-devel] [RFC] Should we use doxygen markup?
Sun Apr 19 16:12:17 CEST 2009
On Sun, Apr 19, 2009 at 03:20:06PM +0200, Vitor Sessak wrote:
> Stefano Sabatini wrote:
>> as recently discussed.
>> Read for example:
>> * 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"
>> "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
similarly, the tags in:
for(i=0; i<8; i++)
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
\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
Size: 189 bytes
Desc: Digital signature
More information about the ffmpeg-devel