r176509 - doc parsing. Add @method and @callback for

[jahanian]

On Mar 5, 2013, at 12:10 PM, Dmitri Gribenko <gribozavr at gmail.com> wrote:

> On Tue, Mar 5, 2013 at 9:40 PM, Fariborz Jahanian <fjahanian at apple.com> wrote:
>> Author: fjahanian
>> Date: Tue Mar  5 13:40:47 2013
>> New Revision: 176509
>> 
>> URL: http://llvm.org/viewvc/llvm-project?rev=176509&view=rev
>> Log:
>> doc parsing. Add @method and @callback for
>> checkings and few other refactoring/cleanup.
>> // rdar://13094352.
>> 
>> Modified:
>>    cfe/trunk/include/clang/AST/CommentCommands.td
>>    cfe/trunk/include/clang/AST/CommentSema.h
>>    cfe/trunk/include/clang/Basic/DiagnosticCommentKinds.td
>>    cfe/trunk/lib/AST/CommentParser.cpp
>>    cfe/trunk/lib/AST/CommentSema.cpp
>>    cfe/trunk/test/Sema/warn-documentation.cpp
>>    cfe/trunk/test/Sema/warn-documentation.m
>> 
>> Modified: cfe/trunk/include/clang/AST/CommentCommands.td
>> URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/AST/CommentCommands.td?rev=176509&r1=176508&r2=176509&view=diff
>> ==============================================================================
>> --- cfe/trunk/include/clang/AST/CommentCommands.td (original)
>> +++ cfe/trunk/include/clang/AST/CommentCommands.td Tue Mar  5 13:40:47 2013
>> @@ -187,8 +187,8 @@ def Protocol  : DeclarationVerbatimLineC
>> def Category  : DeclarationVerbatimLineCommand<"category">;
>> def Template  : DeclarationVerbatimLineCommand<"template">;
>> def Function  : FunctionDeclarationVerbatimLineCommand<"function">;
>> -def Method    : DeclarationVerbatimLineCommand<"method">;
>> -def Callback  : DeclarationVerbatimLineCommand<"callback">;
>> +def Method    : FunctionDeclarationVerbatimLineCommand<"method">;
>> +def Callback  : FunctionDeclarationVerbatimLineCommand<"callback">;
>> def Const     : DeclarationVerbatimLineCommand<"const">;
>> def Constant  : DeclarationVerbatimLineCommand<"constant">;
>> def Struct    : DeclarationVerbatimLineCommand<"struct">;
>> 
>> Modified: cfe/trunk/include/clang/AST/CommentSema.h
>> URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/AST/CommentSema.h?rev=176509&r1=176508&r2=176509&view=diff
>> ==============================================================================
>> --- cfe/trunk/include/clang/AST/CommentSema.h (original)
>> +++ cfe/trunk/include/clang/AST/CommentSema.h Tue Mar  5 13:40:47 2013
>> @@ -206,6 +206,7 @@ public:
>>   void resolveParamCommandIndexes(const FullComment *FC);
>> 
>>   bool isFunctionDecl();
>> +  bool isCallbackDecl();
> 
> Please add a documentation comment that this function returns true for
> variables that are function pointers.  Or rename it to
> isFunctionPointerVarDecl() -- the latter is better, IMHO.
> 
>>   bool isObjCPropertyDecl();
>>   bool isTemplateOrSpecialization();
>> 
>> 
>> Modified: cfe/trunk/include/clang/Basic/DiagnosticCommentKinds.td
>> URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Basic/DiagnosticCommentKinds.td?rev=176509&r1=176508&r2=176509&view=diff
>> ==============================================================================
>> --- cfe/trunk/include/clang/Basic/DiagnosticCommentKinds.td (original)
>> +++ cfe/trunk/include/clang/Basic/DiagnosticCommentKinds.td Tue Mar  5 13:40:47 2013
>> @@ -74,8 +74,8 @@ def warn_doc_param_not_attached_to_a_fun
>>   InGroup<Documentation>, DefaultIgnore;
>> 
>> def warn_doc_function_not_attached_to_a_function_decl : Warning<
>> -  "'@function' command used in a comment that is attached to "
>> -  "a non-function declaration immediately following it">,
>> +  "'%select{\\|@}0%1' command used in a comment that is attached to a non-%2 "
>> +  "declaration immediately following it">,
> 
> Please replace %2 with %select.  We should not pass translatable
> strings from .cpp into diagnostics.  Or you could also reword the text
> like this to avoid the issue altogether:
> 
> "function command should be used in a comment attached to a function
> declaration"
> 
> "callback command should be used in a comment attached to a function
> or ??? declaration"  /* sorry, I don't know semantics of @callback */
> 
> "method command ..."
> 
>>   InGroup<Documentation>, DefaultIgnore;
>> 
>> def warn_doc_param_duplicate : Warning<
>> 
>> Modified: cfe/trunk/lib/AST/CommentParser.cpp
>> URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/lib/AST/CommentParser.cpp?rev=176509&r1=176508&r2=176509&view=diff
>> ==============================================================================
>> --- cfe/trunk/lib/AST/CommentParser.cpp (original)
>> +++ cfe/trunk/lib/AST/CommentParser.cpp Tue Mar  5 13:40:47 2013
>> @@ -706,8 +706,6 @@ VerbatimLineComment *Parser::parseVerbat
>>                                                 TextBegin,
>>                                                 Text);
>>   consumeToken();
>> -  S.checkFunctionDeclVerbatimLine(VL);
>> -
>>   return VL;
>> }
>> 
>> 
>> Modified: cfe/trunk/lib/AST/CommentSema.cpp
>> URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/lib/AST/CommentSema.cpp?rev=176509&r1=176508&r2=176509&view=diff
>> ==============================================================================
>> --- cfe/trunk/lib/AST/CommentSema.cpp (original)
>> +++ cfe/trunk/lib/AST/CommentSema.cpp Tue Mar  5 13:40:47 2013
>> @@ -1,4 +1,4 @@
>> -//===--- CommentSema.cpp - Doxygen comment semantic analysis --------------===//
>> +class//===--- CommentSema.cpp - Doxygen comment semantic analysis --------------===//
>> //
>> //                     The LLVM Compiler Infrastructure
>> //
>> @@ -91,9 +91,11 @@ ParamCommandComment *Sema::actOnParamCom
>> void Sema::checkFunctionDeclVerbatimLine(const BlockCommandComment *Comment) {
>>   const CommandInfo *Info = Traits.getCommandInfo(Comment->getCommandID());
>>   if (Info->IsFunctionDeclarationCommand &&
>> -      !isFunctionDecl())
>> +      !isFunctionDecl() && !isCallbackDecl())
>>     Diag(Comment->getLocation(),
>>          diag::warn_doc_function_not_attached_to_a_function_decl)
>> +    << Comment->getCommandMarker()
>> +    << Info->Name << Info->Name
>>     << Comment->getSourceRange();
> 
> This diagnostic is not as precise as it could be.  For example, it
> would allow @method for a function pointer variable.

Yes. I left this out. As it is not urgent at the time.
- fariborz


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20130305/b339d0dc/attachment.html>