[cfe-commits] [PATCH] Warning to help keep deprecation in comments and in attributes in sync

[Douglas Gregor]

On Sep 15, 2012, at 11:48 AM, Dmitri Gribenko <gribozavr at gmail.com> wrote:

> Hello,
> 
> @Doug: CC'ing you since you requested this.
> 
> The attached patch adds a warning for cases like:
> 
> /// Aaa
> /// \deprecated
> void test_deprecated_4(int a);
> 
> That is, comment has \deprecated but declaration does not have a
> deprecation attribute (deprecated or unavailable).

Perhaps also check for the 'availability' attribute. 

> This warning is under a separate flag,
> -Wdocumentation-deprecated-not-sync, so it can be turned off easily
> while leaving other -Wdocumentation warnings on.

Okay. Can we drop the 'not' from the name?

> I did not add a fix-it note because it would appear inconsistently:
> 1. in case the comment is attached to a declaration we can emit a fix-it easily;
> 2. in case the comment is attached to the function declaration that is
> a definition, a whole new declaration needs to be added (because gcc
> does not allow attributes on a function definition).

It's okay that we can't always provide a Fix-It; we still get a lot of value from having it in many cases. I recommend adding the Fix-It. 

> I don't think that we need to add a warning with reverse logic about
> missing \deprecated, since documentation processing tools based on
> clang should be smart enough to look at attributes.

I agree. 

> Please review.

Looks good, with one more comment: "declaration" is misspelled in the warning text. 

> Dmitri
> 
> -- 
> main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if
> (j){printf("%d\n",i);}}} /*Dmitri Gribenko <gribozavr at gmail.com>*/
> <deprecated-not-sync-v1.patch>