Comment parsing: add more comments to CommentCommands.td

I hope the ASCII art delimiters are OK, since they group *groups* of commands --
that is really helpful.

llvm-svn: 174114

clang/include/clang/AST/CommentCommands.td

@@ -1,3 +1,7 @@
+//===----------------------------------------------------------------------===//
+// Define command classes.
+//===----------------------------------------------------------------------===//
+
 class Command<string name> {
   string Name = name;
   string EndCommandName = "";
@@ -55,6 +59,10 @@ class DeclarationVerbatimLineCommand<string name> :
   let IsDeclarationCommand = 1;
 }
 
+//===----------------------------------------------------------------------===//
+// InlineCommand
+//===----------------------------------------------------------------------===//
+
 def B  : InlineCommand<"b">;
 def C  : InlineCommand<"c">;
 def P  : InlineCommand<"p">;
@@ -62,6 +70,10 @@ def A  : InlineCommand<"a">;
 def E  : InlineCommand<"e">;
 def Em : InlineCommand<"em">;
 
+//===----------------------------------------------------------------------===//
+// BlockCommand
+//===----------------------------------------------------------------------===//
+
 def Brief : BlockCommand<"brief"> { let IsBriefCommand = 1; }
 def Short : BlockCommand<"short"> { let IsBriefCommand = 1; }
 
@@ -71,17 +83,22 @@ def Result  : BlockCommand<"result"> { let IsReturnsCommand = 1; }
 
 def Param : BlockCommand<"param"> { let IsParamCommand = 1; }
 
-// Doxygen
+// Doxygen command for template parameter documentation.
 def Tparam : BlockCommand<"tparam"> { let IsTParamCommand = 1; }
 
-// HeaderDoc
+// HeaderDoc command for template parameter documentation.
 def Templatefield : BlockCommand<"templatefield"> { let IsTParamCommand = 1; }
 
 def Deprecated : BlockCommand<"deprecated"> {
   let IsEmptyParagraphAllowed = 1;
   let IsDeprecatedCommand = 1;
 }
+
 def Headerfile : BlockCommand<"headerfile"> { let IsHeaderfileCommand = 1; }
+
+// We don't do any additional semantic analysis for the following
+// BlockCommands.  It might be a good idea to do something extra for them, but
+// for now we model them as plain BlockCommands.
 def Author     : BlockCommand<"author">;
 def Authors    : BlockCommand<"authors">;
 def Bug        : BlockCommand<"bug">;
@@ -101,6 +118,10 @@ def Todo       : BlockCommand<"todo">;
 def Version    : BlockCommand<"version">;
 def Warning    : BlockCommand<"warning">;
 
+//===----------------------------------------------------------------------===//
+// VerbatimBlockCommand
+//===----------------------------------------------------------------------===//
+
 defm Code      : VerbatimBlockCommand<"code", "endcode">;
 defm Verbatim  : VerbatimBlockCommand<"verbatim", "endverbatim">;
 defm Htmlonly  : VerbatimBlockCommand<"htmlonly", "endhtmlonly">;
@@ -112,11 +133,16 @@ defm Rtfonly   : VerbatimBlockCommand<"rtfonly", "endrtfonly">;
 defm Dot : VerbatimBlockCommand<"dot", "enddot">;
 defm Msc : VerbatimBlockCommand<"msc", "endmsc">;
 
-// These commands have special support in lexer.
+// These three commands have special support in CommentLexer to recognize their
+// names.
 def  FDollar  : VerbatimBlockCommand<"f$">; // Inline LaTeX formula
 defm FBracket : VerbatimBlockCommand<"f[", "f]">; // Displayed LaTeX formula
 defm FBrace   : VerbatimBlockCommand<"f{", "f}">; // LaTeX environment
 
+//===----------------------------------------------------------------------===//
+// VerbatimLineCommand
+//===----------------------------------------------------------------------===//
+
 def Defgroup   : VerbatimLineCommand<"defgroup">;
 def Ingroup    : VerbatimLineCommand<"ingroup">;
 def Addtogroup : VerbatimLineCommand<"addtogroup">;
@@ -132,6 +158,10 @@ def Mainpage : VerbatimLineCommand<"mainpage">;
 def Subpage  : VerbatimLineCommand<"subpage">;
 def Ref      : VerbatimLineCommand<"ref">;
 
+//===----------------------------------------------------------------------===//
+// DeclarationVerbatimLineCommand
+//===----------------------------------------------------------------------===//
+
 // Doxygen commands.
 def Fn        : DeclarationVerbatimLineCommand<"fn">;
 def Namespace : DeclarationVerbatimLineCommand<"namespace">;