[pulseaudio-discuss] [PATCH] doxygen: Replace "\deprecated" with "\b Deprecated."

[Arun Raghavan]

On Mon, 2013-11-11 at 13:54 +0100, Thomas Martitz wrote:
> Am 11.11.2013 12:43, schrieb Tanu Kaskinen:
> > On Fri, 2013-11-08 at 20:29 +0100, Thomas Martitz wrote:
> >> Am 08.11.2013 14:46, schrieb Tanu Kaskinen:
> >>> The effect of the \deprecated tag is (for a reason unknown to me) that
> >>> all documentation for the tagged entity is removed. That's not nice,
> >>> so this patch replaces the tag with plain text "Deprecated" with bold
> >>> formatting.
> >>
> >> Have you tried "GENERATE_DEPRECATEDLIST = YES" in doxygen.conf? It's
> >> seems to be set to NO.
> > No, I hadn't tried that. Now I have. The result was that in the summary
> > part of e.g. pa_card_port_info there was no text for the "profiles"
> > field, but the detailed documentation for "profiles" contained
> > everything it was supposed to, so setting GENERATE_DEPRECATEDLIST = YES
> > was a definite improvement. I still would prefer to make it easy to see
> > already in the summary section that the "profiles" field is deprecated,
> > so I'd prefer to merge this patch, but if I'm alone with that opinion,
> > I'm fine with just changing GENERATE_DEPRECATEDLIST to YES.
> 
> 
> IMO the deprecated information shouldn't be removed from doxygen. You 
> can do some interesting things with doxygen (other than generating HTML 
> docs) provided it has all necessary information. Perhaps there is some 
> other way to promote this text into the summary. On the other hand 
> people that have to deal with the data structure need to look at the 
> details anyway so it might not be a big deal if it's not in the summary.

I agree. Perhaps something like \deprecated { \warning { … } } would
work better.

-- Arun