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

[Thomas Martitz]

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.

Best regards.