[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