[FFmpeg-devel] [RFC] Should we use doxygen markup?
Vitor Sessak
vitor1001
Sun Apr 19 15:20:06 CEST 2009
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.
-Vitor
More information about the ffmpeg-devel
mailing list