[Wdocumentation][RFC] Improve identifier's of \param

[Mordante]

Summary

This fixes several issues with the processing of identifiers of a \param command:

Like Doxygen allow multiple identifiers in one \param command

For example:

/// \param foo, bar The description of foo and bar.
void fun(int foo, int bar);

Was interpreted as:

• a single identifier foo,
• a description of bar The description of foo and bar.

It will now be interpreted as:

• two identifiers foo and bar
• a description of The description of foo and bar.

Likewise:

/// \param foo,bar The description of foo and bar.
void fun(int foo, int bar);

Was interpreted as:

• a single identifier foo,bar
• a description of The description of foo and bar.

It will now be interpreted as:

• two identifiers foo and bar
• a description of The description of foo and bar.

Improved identifier detection

/// \param 42foo The description.
void fun(int foo);

The 42foo is not a valid identifier and will give a warning.

/// \param foo# The description.
void fun(int foo);

Will also trigger a warning since the identifier contains invalid characters.

Improved typo correction of variadic arguments

For example:

/// \param .. The description.
void fun(...);

Will suggest to change the identifier .. to .... This will only happen if the function is variadic and the variadic argument has no documentation.

Warn about undocumented function arguments

If after the typo correction function arguments are not documented yet there will be a warning about these arguments. This only happens if at least one \param comment is used.

/// \param foo The description of foo and bar.
void fun(int foo, int bar);

This will warn about the undocumented bar.

/// fun's arguments are not documented
void fun(int foo, int bar);

This will /not/ warn about the undocumented foo and bar.

Questions

The undocumented function argument is part of -Wdocumentation. Should it remain here or be part of its own -Wdocumentation-undocumented-arguments?

The clang-doc has minimal changes to support the new feature. @juliehockett anything you want to improve. If so should these changes be in this patch or a follow-up patch?

TODOs

• The \tparam can be improved in a similar fashion. This will be done in a separate patch.
• The identifier detection could try a bit harder to extract the identifier. It could detect and propose fixits for references, pointers, and arrays. For example it could offer a fixit for &*identifier[...]. This will be done in a separate patch.

Fixes PR14335: [-Wdocumentation] Multiple identifiers (comma,separated) are not recognized on \param

[merge_guards_bot]

Unit tests: unknown.

clang-tidy: fail. Please fix clang-tidy findings.

clang-format: fail. Please format your changes with clang-format by running git-clang-format HEAD^ or applying this patch.

Build artifacts: diff.json, clang-tidy.txt, clang-format.patch, CMakeCache.txt, console-log.txt

[Mordante]

The merge bot noticed I forgot to update clang's unittests. Will look at that.

[Mordante]

Fixes the compilation issues with the clang unit tests.

[merge_guards_bot]

Unit tests: unknown.

clang-tidy: fail. Please fix clang-tidy findings.

clang-format: fail. Please format your changes with clang-format by running git-clang-format HEAD^ or applying this patch.

Build artifacts: diff.json, clang-tidy.txt, clang-format.patch, CMakeCache.txt, console-log.txt

[gribozavr2]

Thank you for the patch!

clang/docs/ReleaseNotes.rst

68

validation *of*

360

Need backticks around \param. Also a spurious "p" at the end of the line.

clang/include/clang-c/Documentation.h

383

Please don't modify existing APIs in libclang -- it provides a stable API and ABI, and what has shipped, can't be changed. New functionality has to be exposed as new functions, while old functions should be kept working to the extent possible. It means that the resulting API can be subpar, but oh well, a stable ABI is a contract of libclang.

clang/include/clang/AST/Comment.h

715–716

"Indices of the parameters referenced by this command in the function declaration."

763–766

setParamIndices

781

Users can already call getArgText, do we need a second function that does the same?

793

Ditto, duplicated API.

797–799

I'd call it getArgument and define it in BlockCommandComment.

804

Why does vararg have an invalid index? Previously it was considered valid.

clang/include/clang/AST/CommentSema.h

111

s/NameArg/NameArgs/

clang/include/clang/Basic/DiagnosticCommentKinds.td

113

This warning should be in a separate group. -Wdocumentation contains generally useful, non-controversial stuff (that would have been an error if documentation comments were a part of the language). Warning about every undocumented parameter is only useful for certain style guides.

(Digression: And even then, I personally question the value of a style rule that requires every parameter (or every public API, or every file, or every whatever else) to be documented. Unless there's a tech writer on the team, in response to a such rule engineers are highly likely just to write useless comments like "\param frobnicator The Frobnicator necessary for this call." Engineers are already doing the best they can when writing comments. The choice we have is not between "no comments for some parameters" and "good comments for every parameter because the warning reminded you", it is between "no comments for some parameters" and "placeholder stuff that people will write to make the warning go away".)

I'd also suggest to implement this functionality in a separate patch.

clang/lib/AST/Comment.cpp

376

Previously, it was necessary for the index to be valid. Why relax the contract? (This change also makes things in consistent with, say, TParam).

clang/lib/AST/CommentParser.cpp

362

Adding lexIdentifier() seems too complicated to me (it is also not *really* an identifier, because we are allowing "..."). I'd stick to consuming characters until a comma or a space, that's a lot simpler. If we lexed an invalid identifier, it won't match any function parameter, and we will get a warning at that point anyway.

clang/lib/AST/CommentSema.cpp

742

Why double-backslash?

744–746

Stale comment (SmallVector)?

745

If ParamVarDocs is a vector of SourceRanges, the comment shouldn't say that it contains AST nodes.

758

Here's one reason why I find the fallback in getParamName to be questionable -- with the fallback, the function does different things depending on the phase of processing. Sometimes it returns the original name as written (before the index is set), and sometimes it returns the name from the function declaration (which can be different, as far as I understand). I'd much prefer to call getParamNameAsWritten here.

852

I'm not sure about this erase call. With this change, once a typo claims an identifier, it is gone no matter how bad the typo was. Even if there's a further, closer, typo, that identifier won't be suggested anymore.

866

Use cast<> instead.

cast<> = dyn_cast<> + assert

1121

I'm not sure I like the heuristic.

// \param foo.bar Something.
void foo(int foo_bar, ...);

Here we would suggest to correct foo.bar to ....

Instead, I'd suggest to throw a "..." identifier into the typo corrector if the function is variadic, and let the edit distance decide.

clang/lib/AST/JSONNodeDumper.cpp

1586

Despite what the old code does (I didn't review it when it was submitted), I think it is more useful to dump the parameter name as written, not as found in the function declaration.

clang/lib/Index/CommentToXML.cpp

745–773

Please also update the XML schema in llvm-project/clang/bindings/xml/comment-xml-schema.rng.

748

Why do we need an extra "<Identifiers>" wrapping the list of parameters?

clang/test/Sema/warn-documentation.cpp

268

Seems redundant to say that the identifier should be valid. Also it is not just any identifier, we can be more specific. WDYT about "a parameter name should be specified after the '\param' command"?

276

I don't think it makes sense to distinguish "not a valid identifier" and "not properly terminated". From the user's perspective, the issue is the same.

389

Would be nice to also add a test for '\param a, a Aaa.'

clang/unittests/AST/CommentParser.cpp

183 ↗

(On Diff #235514)

s/ParamName/ParamNames/

[Mordante]

Thanks for the review!

I only answered to the larger issues to get a better feeling of the direction the patch should go. Once that's clear I'll make a new patch and also address the smaller issues.

clang/include/clang-c/Documentation.h

383

I thought I had read this API was allowed to change, but required adding information to the release notes. (I can't find it quickly.)
I'll undo the changes to the existing functions and add new functions instead.

clang/include/clang/AST/Comment.h

781

I thought it made sense to offer these helper functions. getParamName seems clearer than getArgText. Of course it's also possible to add documentation instead of a helper function. What do you prefer?

Note: This function is the replacement of getParamNameAsWritten, so I can also reinstate its former name.

804

Before a lot of code first tested whether the index was valid and then depending on the vararg state do a different codepath. I thought it was very confusing that if the function returned true it was no guarantee it was safe to access DeclInfo::ParamVars[Idx].

clang/include/clang/Basic/DiagnosticCommentKinds.td

113

I'll move it to its own patch.

clang/lib/AST/Comment.cpp

376

IMO it makes it easier on the caller site. If it wants the name of the variable in the current FullComment context they can simply call this function. Then they don't need to validate whether the index is valid or not. (I intend to do a similar patch for TParam.)

clang/lib/AST/CommentSema.cpp

758

The difference is now in the FullComment argument instead of the name. But it seems that is not clear.

852

True, but I thought it was not allowed for fixits to give invalid hints. Using the same correction twice will result in new warnings. What do you think?

866

Thanks for the hint!

1121

This heuristic works at the moment. The lexIdentifier will not accept foo.bar. However since you requested to remove the lexIdentifier your approach makes more sense.

clang/lib/AST/JSONNodeDumper.cpp

1586

You want the behaviour for all AST dumpers? (I assume yes)

clang/lib/Index/CommentToXML.cpp

748

What would you propose instead? No "<Indentifiers>" and just a list of "<identifier>" ?

clang/test/Sema/warn-documentation.cpp

268

Agreed.

276

I'm not entirely sure. However after I remove the lexIdentifier 9aaa will become a valid identifier. So I'll remove this warning.

[gribozavr2]

clang/include/clang-c/Documentation.h

383

I thought I had read this API was allowed to change

It would be interesting to find that doc. As far as I understand, libclang has a strict API & ABI stability rule.

I'll undo the changes to the existing functions and add new functions instead.

Thanks!

clang/include/clang/AST/Comment.h

781

I prefer using getArgText. It works uniformly for all block commands.

clang/lib/AST/Comment.cpp

376

The issue is that it is unclear what kind of name they get -- the as written name, or the mapped one.

clang/lib/AST/CommentSema.cpp

852

True, but I thought it was not allowed for fixits to give invalid hints.

Fixits are allowed to be incorrect. Any fixit can be incorrect semantically (the user actually intended something different), even if it perfectly fixes the C++ and Doxygen issues.

Using the same correction twice will result in new warnings.

I don't think users will apply all fixits without subsequent review. In an IDE setting, users pick and choose fixits.

Also, not reusing the same correction twice does not guarantee that the fixes are correct; it only ensures that we won't have a new warning about duplicated parameter names.

clang/lib/AST/JSONNodeDumper.cpp

1586

Yes, I'd prefer it everywhere.

clang/lib/Index/CommentToXML.cpp

748

Yep, "<Parameter>" can directly contain multiple "<Identifier>" tags.

[Mordante]

So if I understand correctly:

• getParamNameAsWritten will become getArgText
• The getParamName will do the translation from the name in the documentation to the name in the current function declaration. If the parameter index is invalid the function will fail (with an assertion error) and not fallback to call getArgText.

clang/include/clang-c/Documentation.h

383

I thought I had read this API was allowed to change

It would be interesting to find that doc. As far as I understand, libclang has a strict API & ABI stability rule.

My interpretation of http://llvm.org/docs/DeveloperPolicy.html#c-api-changes gave me this impression.

[gribozavr2]

In D71966#1840957, @Mordante wrote:

So if I understand correctly:

• getParamNameAsWritten will become getArgText
• The getParamName will do the translation from the name in the documentation to the name in the current function declaration. If the parameter index is invalid the function will fail (with an assertion error) and not fallback to call getArgText.

Yes, that would be my preference. Thanks!

clang/include/clang-c/Documentation.h

383

I see. Index.h explains the policy for libclang: https://github.com/llvm/llvm-project/blob/master/clang/include/clang-c/Index.h#L32-L33

If you feel like doing so, feel free to submit a patch for the developer policy to clarify libclang stability guarantees.

[Mordante]

clang/lib/AST/CommentSema.cpp

1121

Any suggestion how to do this? The SimpleTypoCorrector expects a NamedDecl, but AFAIK ... isn't a NamedDecl.

[aaronpuchert]

Thanks for working on this, I'd like to see this being fixed.

clang/include/clang-c/Documentation.h

383

I think @gribozavr2 is correct here, the chapter in the developer policy refers to the C API of LLVM, not Clang. The Clang documentation also says that libclang should be stable (http://clang.llvm.org/docs/Tooling.html#libclang).

[aaronpuchert]

@Mordante, do you have plans to get back to this? Otherwise I'd like to pick it up.

I'd probably concentrate on multiple parameter support for now, and delegate identifier validation, typo correction for variadic functions, and the undocumented parameter warning to separate changes.

[Mordante]

Sorry I missed your message. At the moment I don't intend to continue with this review. Do you want to commandeer this one or do you prefer me to abandon it?

clang-tools-extra/clang-doc/Representation.h

struct CommentInfo {
   bool Explicit = false; // Indicates if the direction of a param is explicit
                          // (for (T)ParamCommand).
   llvm::SmallVector<SmallString<16>, 4>
       AttrKeys; // List of attribute keys (for HTML).
   llvm::SmallVector<SmallString<16>, 4>
       AttrValues; // List of attribute values for each key (for HTML).
   llvm::SmallVector<SmallString<16>, 4>
       Args; // List of arguments to commands (for InlineCommand).
+            // Parameter names (for ParamCommand).
   std::vector<std::unique_ptr<CommentInfo>>
       Children; // List of child comments for this CommentInfo.
 };
 
 struct Reference {
   Reference() = default;
   Reference(llvm::StringRef Name) : Name(Name) {}
   // An empty path means the info is in the global namespace because the path is

clang-tools-extra/clang-doc/Serialize.cpp

for (unsigned I = 0, E = C->getNumArgs(); I < E; ++I)
     CurrentCI.Args.push_back(C->getArgText(I));
 }
 
 void ClangDocCommentVisitor::visitParamCommandComment(
     const ParamCommandComment *C) {
   CurrentCI.Direction =
       ParamCommandComment::getDirectionAsString(C->getDirection());
   CurrentCI.Explicit = C->isDirectionExplicit();
-  if (C->hasParamName())
-    CurrentCI.ParamName = C->getParamNameAsWritten();
+  for (unsigned I = 0, E = C->getNumParams(); I != E; ++I) {
+    StringRef ParamName = C->getParamName(I);
+    if (I != 0)
+      CurrentCI.ParamName += ", ";
+    CurrentCI.ParamName += ParamName;
+
+    CurrentCI.Args.push_back(ParamName);
+  }
 }
 
 void ClangDocCommentVisitor::visitTParamCommandComment(
     const TParamCommandComment *C) {
   if (C->hasParamName())
     CurrentCI.ParamName = C->getParamNameAsWritten();
 }
 

clang/docs/ReleaseNotes.rst

 - -Wtautological-bitwise-compare is a new warning group.  This group has the
   current warning which diagnoses the tautological comparison of a bitwise
   operation and a constant. The group also has the new warning which diagnoses
   when a bitwise-or with a non-negative value is converted to a bool, since
   that bool will always be true.
 - -Wbitwise-conditional-parentheses will warn on operator precedence issues
   when mixing bitwise-and (&) and bitwise-or (|) operator with the
   conditional operator (?:).
+- -Wdocumentation properly handles Doxygen comments with multiple identifiers in
+  one \param command. The validation whether the name of the identifier is valid
+  has been improved.
+- -Wdocumentation now warns about not documented function arguments if at least
+  once \param command is supplied in the function's documentation.
 
 Non-comprehensive list of changes in this release
 -------------------------------------------------
 
 * In both C and C++ (C17 ``6.5.6p8``, C++ ``[expr.add]``), pointer arithmetic is
   only permitted within arrays. In particular, the behavior of a program is not
   defined if it adds a non-zero offset (or in C, any offset) to a null pointer,
   or if it forms a null pointer by subtracting an integer from a non-null
- Clang-format now supports JavaScript null operators.
   .. code-block:: c++
 
     const x = foo ?? default;
     const z = foo?.bar?.baz;
 
 libclang
 --------
 
-- ...
+- Function ``clang_ParamCommandComment_getNumParams`` has been added to
+  determine the number of parameters to a single Doxygen \param command.p
+- Function ``clang_ParamCommandComment_isVarArgParam`` has been added to
+  determine the whether the parameter refers to the variadic argument.
+- Function ``clang_ParamCommandComment_getParamName`` has been modified. It
+  takes an additional index argument.
+- Function ``clang_ParamCommandComment_isParamIndexValid`` has been modified. It
+  takes an additional index argument.
+- Function ``clang_ParamCommandComment_getParamIndex`` has been modified. It
+  takes an additional index argument.
 
 Static Analyzer
 ---------------
 
 - The Clang analyzer checker ``DeadStores`` gets a new option called
   ``WarnForDeadNestedAssignments`` to detect nested dead assignments
   (enabled by default).
 - ...

clang/include/clang-c/Documentation.h

  * \returns paragraph argument of the block command.
  */
 CINDEX_LINKAGE
 CXComment clang_BlockCommandComment_getParagraph(CXComment Comment);
 
 /**
  * \param Comment a \c CXComment_ParamCommand AST node.
  *
- * \returns parameter name.
+ * \returns the number of identifiers.
  */
 CINDEX_LINKAGE
-CXString clang_ParamCommandComment_getParamName(CXComment Comment);
+unsigned clang_ParamCommandComment_getNumParams(CXComment Comment);
 
 /**
  * \param Comment a \c CXComment_ParamCommand AST node.
  *
- * \returns non-zero if the parameter that this AST node represents was found
+ * \param Idx the (zero-based) index of the identifier of the param command.
+ *
+ * \returns identifier name.
+ */
+CINDEX_LINKAGE
+CXString clang_ParamCommandComment_getParamName(CXComment Comment,
+                                                unsigned Idx);
+
+/**
+ * \param Comment a \c CXComment_ParamCommand AST node.
+ *
+ * \param Idx the (zero-based) index of the identifier of the param command.
+ *
+ * \returns non-zero if the identifier that this AST node represents was found
  * in the function prototype and \c clang_ParamCommandComment_getParamIndex
  * function will return a meaningful value.
  */
 CINDEX_LINKAGE
-unsigned clang_ParamCommandComment_isParamIndexValid(CXComment Comment);
+unsigned clang_ParamCommandComment_isParamIndexValid(CXComment Comment,
+                                                     unsigned Idx);
 
 /**
  * \param Comment a \c CXComment_ParamCommand AST node.
  *
+ * \param Idx the (zero-based) index of the identifier of the param command.
+ *
+ * \returns non-zero if the identifier that this AST node represents was found
+ * in the function prototype and points to the variadic argument.
+ */
+CINDEX_LINKAGE
+unsigned clang_ParamCommandComment_isVarArgParam(CXComment Comment,
+                                                 unsigned Idx);
+
+/**
+ * \param Comment a \c CXComment_ParamCommand AST node.
+ *
+ * \param Idx the (zero-based) index of the identifier of the param command.
+ *
  * \returns zero-based parameter index in function prototype.
  */
 CINDEX_LINKAGE
-unsigned clang_ParamCommandComment_getParamIndex(CXComment Comment);
+unsigned clang_ParamCommandComment_getParamIndex(CXComment Comment,
+                                                 unsigned Idx);
 
 /**
  * \param Comment a \c CXComment_ParamCommand AST node.
  *
  * \returns non-zero if parameter passing direction was specified explicitly in
  * the comment.
  */
 CINDEX_LINKAGE

clang/include/clang/AST/Comment.h

CommandMarkerKind getCommandMarker() const LLVM_READONLY {
     return static_cast<CommandMarkerKind>(
         BlockCommandCommentBits.CommandMarker);
   }
 };
 
 /// Doxygen \\param command.
 class ParamCommandComment : public BlockCommandComment {
 private:
-  /// Parameter index in the function declaration.
-  unsigned ParamIndex;
+  /// The index of the identifier in the function declaration.
+  MutableArrayRef<unsigned> ParamIndex;
 
 public:
   enum : unsigned {
     InvalidParamIndex = ~0U,
     VarArgParamIndex = ~0U/*InvalidParamIndex*/ - 1U
   };
 
-  ParamCommandComment(SourceLocation LocBegin,
-                      SourceLocation LocEnd,
-                      unsigned CommandID,
-                      CommandMarkerKind CommandMarker) :
-      BlockCommandComment(ParamCommandCommentKind, LocBegin, LocEnd,
+  ParamCommandComment(SourceLocation LocBegin, SourceLocation LocEnd,
+                      unsigned CommandID, CommandMarkerKind CommandMarker)
+      : BlockCommandComment(ParamCommandCommentKind, LocBegin, LocEnd,
                             CommandID, CommandMarker),
-      ParamIndex(InvalidParamIndex) {
+        ParamIndex() {
     ParamCommandCommentBits.Direction = In;
     ParamCommandCommentBits.IsDirectionExplicit = false;
   }
 
   static bool classof(const Comment *C) {
     return C->getCommentKind() == ParamCommandCommentKind;
   }
 
bool isDirectionExplicit() const LLVM_READONLY {
     return ParamCommandCommentBits.IsDirectionExplicit;
   }
 
   void setDirection(PassDirection Direction, bool Explicit) {
     ParamCommandCommentBits.Direction = Direction;
     ParamCommandCommentBits.IsDirectionExplicit = Explicit;
   }
 
-  bool hasParamName() const {
-    return getNumArgs() > 0;
+  unsigned getNumParams() const LLVM_READONLY {
+    assert(Args.size() == ParamIndex.size());
+    return ParamIndex.size();
   }
 
-  StringRef getParamName(const FullComment *FC) const;
+  void setParamIndex(MutableArrayRef<unsigned> Idx) {
+    assert(ParamIndex.empty() && "Can't initialize more than once.");
+    ParamIndex = Idx;
+  }
 
-  StringRef getParamNameAsWritten() const {
-    return Args[0].Text;
+  void setParamIndex(unsigned Idx, unsigned ArgumentIndex) {
+    assert(Idx < ParamIndex.size());
+    ParamIndex[Idx] = ArgumentIndex;
   }
 
-  SourceRange getParamNameRange() const {
-    return Args[0].Range;
+  unsigned getParamIndex(unsigned Idx) const LLVM_READONLY {
+    assert(Idx < ParamIndex.size());
+    return ParamIndex[Idx];
   }
 
-  bool isParamIndexValid() const LLVM_READONLY {
-    return ParamIndex != InvalidParamIndex;
+  /// Returns the name of the identifier as used in the \\param command.
+  ///
+  /// @param Idx The index of the identifier in the \\param command.
+  StringRef getParamName(unsigned Idx) const LLVM_READONLY {
+    return getArgText(Idx);
   }
 
-  bool isVarArgParam() const LLVM_READONLY {
-    return ParamIndex == VarArgParamIndex;
+  /// Returns the name of the function argument as written in \p FC.
+  ///
+  /// If the identifier is not mapped to an argument it returns the identifer
+  /// used in the \\param command.
+  ///
+  /// @param Idx The index of the identifier in the \\param command.
+  StringRef getParamName(const FullComment *FC, unsigned Idx) const;
+
+  SourceRange getParamRange(unsigned Idx) const LLVM_READONLY {
+    return getArgRange(Idx);
   }
 
-  void setIsVarArgParam() {
-    ParamIndex = VarArgParamIndex;
-    assert(isParamIndexValid());
+  const Argument *getParam(unsigned Idx) const LLVM_READONLY {
+    assert(Idx < Args.size());
+    return &Args[Idx];
   }
 
-  unsigned getParamIndex() const LLVM_READONLY {
-    assert(isParamIndexValid());
-    assert(!isVarArgParam());
-    return ParamIndex;
+  bool isParamIndexValid(unsigned Idx) const LLVM_READONLY {
+    assert(Idx < ParamIndex.size());
+    return !isVarArgParam(Idx) && ParamIndex[Idx] != InvalidParamIndex;
   }
 
-  void setParamIndex(unsigned Index) {
-    ParamIndex = Index;
-    assert(isParamIndexValid());
-    assert(!isVarArgParam());
+  bool isVarArgParam(unsigned Idx) const LLVM_READONLY {
+    assert(Idx < ParamIndex.size());
+    return ParamIndex[Idx] == VarArgParamIndex;
   }
 };
 
 /// Doxygen \\tparam command, describes a template parameter.
 class TParamCommandComment : public BlockCommandComment {
 private:
   /// If this template parameter name was resolved (found in template parameter
   /// list), then this stores a list of position indexes in all template

clang/include/clang/AST/CommentSema.h

ParamCommandComment *actOnParamCommandStart(SourceLocation LocBegin,
                                               unsigned CommandID,
                                               CommandMarkerKind CommandMarker);
 
   void actOnParamCommandDirectionArg(ParamCommandComment *Command,
                                      SourceLocation ArgLocBegin,
                                      SourceLocation ArgLocEnd,
                                      StringRef Arg);
 
-  void actOnParamCommandParamNameArg(ParamCommandComment *Command,
-                                     SourceLocation ArgLocBegin,
-                                     SourceLocation ArgLocEnd,
-                                     StringRef Arg);
+  void
+  actOnParamCommandParamNameArg(ParamCommandComment *Command,
+                                ArrayRef<BlockCommandComment::Argument> Args);
 
   void actOnParamCommandFinish(ParamCommandComment *Command,
                                ParagraphComment *Paragraph);
 
   TParamCommandComment *actOnTParamCommandStart(SourceLocation LocBegin,
                                                 SourceLocation LocEnd,
                                                 unsigned CommandID,
                                                 CommandMarkerKind CommandMarker);

clang/include/clang/Basic/DiagnosticCommentKinds.td

 
 def warn_doc_param_not_found : Warning<
   "parameter '%0' not found in the function declaration">,
   InGroup<Documentation>, DefaultIgnore;
 
 def note_doc_param_name_suggestion : Note<
   "did you mean '%0'?">;
 
+def warn_doc_param_undocumented : Warning<
+  "parameter '%0' is not documented">,
+  InGroup<Documentation>, DefaultIgnore;
+
+def warn_doc_param_identifier_invalid : Warning<
+  "'%select{\\|@}0param' command does not have a valid identifier">,
+  InGroup<Documentation>, DefaultIgnore;
+
+def warn_doc_param_identifier_no_terminator : Warning<
+  "'%select{\\|@}0param' command's identifier is not properly terminated">,
+  InGroup<Documentation>, DefaultIgnore;
+
 // tparam command
 
 def warn_doc_tparam_not_attached_to_a_template_decl : Warning<
   "'%select{\\|@}0tparam' command used in a comment that is not attached to "
   "a template declaration">,
   InGroup<Documentation>, DefaultIgnore;
 
 def warn_doc_tparam_duplicate : Warning<

clang/lib/AST/Comment.cpp

void DeclInfo::fill() {
   case Decl::Enum:
     Kind = EnumKind;
     break;
   }
 
   IsFilled = true;
 }
 
-StringRef ParamCommandComment::getParamName(const FullComment *FC) const {
-  assert(isParamIndexValid());
-  if (isVarArgParam())
+StringRef ParamCommandComment::getParamName(const FullComment *FC,
+                                            unsigned Idx) const {
+  unsigned ParamIdx = getParamIndex(Idx);
+  switch (ParamIdx) {
+  case InvalidParamIndex:
+    return getParamName(Idx);
+
+  case VarArgParamIndex:
     return "...";
-  return FC->getDeclInfo()->ParamVars[getParamIndex()]->getName();
+
+  default:
+    return FC->getDeclInfo()->ParamVars[ParamIdx]->getName();
+  }
 }
 
 StringRef TParamCommandComment::getParamName(const FullComment *FC) const {
   assert(isPositionValid());
   const TemplateParameterList *TPL = FC->getDeclInfo()->TemplateParameters;
   for (unsigned i = 0, e = getDepth(); i != e; ++i) {
     if (i == e-1)
       return TPL->getParam(getIndex(i))->getName();

clang/lib/AST/CommentParser.cpp

bool lexWord(Token &Tok) {
 
     memcpy(TextPtr, WordText.c_str(), Length + 1);
     StringRef Text = StringRef(TextPtr, Length);
 
     formTokenWithChars(Tok, Loc, WordBegin, Length, Text);
     return true;
   }
 
+  bool lexIdentifier(Token &Tok) {
+    if (isEnd())
+      return false;
+
+    Position SavedPos = Pos;
+    consumeWhitespace();
+    if (isEnd()) {
+      Pos = SavedPos;
+      return false;
+    }
+
+    SmallString<32> IdentifierText;
+    const char *IdentifierBegin = Pos.BufferPtr;
+    SourceLocation Loc = getSourceLocation();
+    char C = peek();
+    if (isIdentifierHead(C)) {
+      IdentifierText.push_back(C);
+      consumeChar();
+      while (!isEnd()) {
+        C = peek();
+        if (isIdentifierBody(C)) {
+          IdentifierText.push_back(C);
+          consumeChar();
+        } else
+          break;
+      }
+    } else if (C == '.') {
+      do {
+        IdentifierText.push_back('.');
+        consumeChar();
+      } while (!isEnd() && peek() == '.');
+    } else {
+      Pos = SavedPos;
+      return false;
+    }
+
+    const unsigned Length = IdentifierText.size();
+    char *TextPtr = Allocator.Allocate<char>(Length + 1);
+
+    memcpy(TextPtr, IdentifierText.c_str(), Length + 1);
+    StringRef Text = StringRef(TextPtr, Length);
+
+    formTokenWithChars(Tok, Loc, IdentifierBegin,
+                       Pos.BufferPtr - IdentifierBegin, Text);
+    return true;
+  }
+
   bool lexDelimitedSeq(Token &Tok, char OpenDelim, char CloseDelim) {
     if (isEnd())
       return false;
 
     Position SavedPos = Pos;
 
     consumeWhitespace();
     SmallString<32> WordText;
bool lexDelimitedSeq(Token &Tok, char OpenDelim, char CloseDelim) {
     memcpy(TextPtr, WordText.c_str(), Length + 1);
     StringRef Text = StringRef(TextPtr, Length);
 
     formTokenWithChars(Tok, Loc, WordBegin,
                        Pos.BufferPtr - WordBegin, Text);
     return true;
   }
 
+  bool lexChar(Token &Tok, char Char) {
+    assert(!isWhitespace(Char));
+    if (isEnd())
+      return false;
+
+    Position SavedPos = Pos;
+
+    consumeWhitespace();
+    SmallString<2> CharText;
+    const char *CharBegin = Pos.BufferPtr;
+    SourceLocation Loc = getSourceLocation();
+    if (!isEnd() && peek() == Char) {
+      CharText.push_back(Char);
+      consumeChar();
+    } else {
+      Pos = SavedPos;
+      return false;
+    }
+
+    const unsigned Length = CharText.size();
+    char *TextPtr = Allocator.Allocate<char>(Length + 1);
+
+    memcpy(TextPtr, CharText.c_str(), Length + 1);
+    StringRef Text = StringRef(TextPtr, Length);
+
+    formTokenWithChars(Tok, Loc, CharBegin, Pos.BufferPtr - CharBegin, Text);
+    return true;
+  }
+
+  bool hasIdentifierTerminator() {
+    if (isEnd())
+      return true;
+
+    char C = peek();
+    return C == ',' || isWhitespace(C);
+  }
+
   /// Put back tokens that we didn't consume.
   void putBackLeftoverTokens() {
     if (isEnd())
       return;
 
     bool HavePartialTok = false;
     Token PartialTok;
     if (Pos.BufferPtr != Pos.BufferStart) {
void Parser::parseParamCommandArgs(ParamCommandComment *PC,
   // Check if argument looks like direction specification: [dir]
   // e.g., [in], [out], [in,out]
   if (Retokenizer.lexDelimitedSeq(Arg, '[', ']'))
     S.actOnParamCommandDirectionArg(PC,
                                     Arg.getLocation(),
                                     Arg.getEndLocation(),
                                     Arg.getText());
 
-  if (Retokenizer.lexWord(Arg))
-    S.actOnParamCommandParamNameArg(PC,
-                                    Arg.getLocation(),
-                                    Arg.getEndLocation(),
-                                    Arg.getText());
+  using Argument = BlockCommandComment::Argument;
+  SmallVector<Token, 4> ArgumentTokens;
+  do {
+    if (Retokenizer.lexIdentifier(Arg)) {
+      ArgumentTokens.push_back(Arg);
+      if (!Retokenizer.hasIdentifierTerminator())
+        Diag(Arg.getEndLocation(),
+             diag::warn_doc_param_identifier_no_terminator)
+            << PC->getCommandMarker()
+            << SourceRange(Arg.getLocation(), Arg.getEndLocation());
+
+    } else if (!ArgumentTokens.empty()) {
+      Diag(Arg.getEndLocation(), diag::warn_doc_param_identifier_invalid)
+          << PC->getCommandMarker() << PC->getSourceRange();
+
+      return;
+    }
+  } while (Retokenizer.lexChar(Arg, ','));
+
+  if (ArgumentTokens.empty()) {
+    Diag(PC->getEndLoc(), diag::warn_doc_param_identifier_invalid)
+        << PC->getCommandMarker() << PC->getSourceRange();
+    return;
+  }
+
+  unsigned NumArgs = ArgumentTokens.size();
+  Argument *Args =
+      new (Allocator.Allocate<Argument>(NumArgs)) Argument[NumArgs];
+
+  std::transform(ArgumentTokens.begin(), ArgumentTokens.end(), &Args[0],
+                 [](const Token &Arg) {
+                   return Argument{
+                       SourceRange(Arg.getLocation(), Arg.getEndLocation()),
+                       Arg.getText()};
+                 });
+
+  S.actOnParamCommandParamNameArg(PC, llvm::makeArrayRef(Args, NumArgs));
 }
 
 void Parser::parseTParamCommandArgs(TParamCommandComment *TPC,
                                     TextTokenRetokenizer &Retokenizer) {
   Token Arg;
   if (Retokenizer.lexWord(Arg))
     S.actOnTParamCommandParamNameArg(TPC,
                                      Arg.getLocation(),

clang/lib/AST/CommentSema.cpp

if (Direction != -1) {
       Diag(ArgLocBegin, diag::warn_doc_param_invalid_direction) << ArgRange;
       Direction = ParamCommandComment::In; // Sane fall back.
     }
   }
   Command->setDirection((ParamCommandComment::PassDirection)Direction,
                         /*Explicit=*/true);
 }
 
-void Sema::actOnParamCommandParamNameArg(ParamCommandComment *Command,
-                                         SourceLocation ArgLocBegin,
-                                         SourceLocation ArgLocEnd,
-                                         StringRef Arg) {
+void Sema::actOnParamCommandParamNameArg(
+    ParamCommandComment *Command,
+    ArrayRef<BlockCommandComment::Argument> Args) {
   // Parser will not feed us more arguments than needed.
   assert(Command->getNumArgs() == 0);
+  assert(Command->getNumParams() == 0);
 
   if (!Command->isDirectionExplicit()) {
     // User didn't provide a direction argument.
     Command->setDirection(ParamCommandComment::In, /* Explicit = */ false);
   }
-  typedef BlockCommandComment::Argument Argument;
-  Argument *A = new (Allocator) Argument(SourceRange(ArgLocBegin,
-                                                     ArgLocEnd),
-                                         Arg);
-  Command->setArgs(llvm::makeArrayRef(A, 1));
+
+  Command->setArgs(Args);
+
+  unsigned Size = Args.size();
+  auto ParamIndex = llvm::makeMutableArrayRef(
+      new (Allocator.Allocate<unsigned>(Size)) unsigned[Size], Size);
+  std::fill(ParamIndex.begin(), ParamIndex.end(),
+            ParamCommandComment::InvalidParamIndex);
+  Command->setParamIndex(ParamIndex);
 }
 
 void Sema::actOnParamCommandFinish(ParamCommandComment *Command,
                                    ParagraphComment *Paragraph) {
   Command->setParagraph(Paragraph);
   checkBlockCommandEmptyParagraph(Command);
 }
 

 
 void Sema::resolveParamCommandIndexes(const FullComment *FC) {
   if (!isFunctionDecl()) {
     // We already warned that \\param commands are not attached to a function
     // decl.
     return;
   }
 
-  SmallVector<ParamCommandComment *, 8> UnresolvedParamCommands;
+  SmallVector<const BlockCommandComment::Argument *, 8> UnresolvedParamCommands;
 
-  // Comment AST nodes that correspond to \c ParamVars for which we have
+  // Comment AST nodes that correspond to \\c ParamVars for which we have
   // found a \\param command or NULL if no documentation was found so far.
-  SmallVector<ParamCommandComment *, 8> ParamVarDocs;
+  // SmallVector<ParamCommandComment *, 8> ParamVarDocs;
+  SmallVector<const SourceRange *, 8> ParamVarDocs;
+  const SourceRange *VarArgDocs = nullptr;
 
   ArrayRef<const ParmVarDecl *> ParamVars = getParamVars();
   ParamVarDocs.resize(ParamVars.size(), nullptr);
 
-  // First pass over all \\param commands: resolve all parameter names.
-  for (Comment::child_iterator I = FC->child_begin(), E = FC->child_end();
-       I != E; ++I) {
-    ParamCommandComment *PCC = dyn_cast<ParamCommandComment>(*I);
-    if (!PCC || !PCC->hasParamName())
-      continue;
-    StringRef ParamName = PCC->getParamNameAsWritten();
+  // Warn about undocumented params, if at least one \\param has been found.
+  // This to avoid warning when none are documented.
+  // TODO Add a flag to always warn?
+  bool WarnUndocumentedParameters = false;
+
+  auto ProcessParameter = [&](ParamCommandComment *PCC, unsigned Idx) {
+    WarnUndocumentedParameters = true;
+    StringRef ParamName = PCC->getParamName(Idx);
 
     // Check that referenced parameter name is in the function decl.
-    const unsigned ResolvedParamIndex = resolveParmVarReference(ParamName,
-                                                                ParamVars);
-    if (ResolvedParamIndex == ParamCommandComment::VarArgParamIndex) {
-      PCC->setIsVarArgParam();
-      continue;
-    }
+    const unsigned ResolvedParamIndex =
+        resolveParmVarReference(ParamName, ParamVars);
+
     if (ResolvedParamIndex == ParamCommandComment::InvalidParamIndex) {
-      UnresolvedParamCommands.push_back(PCC);
-      continue;
+      UnresolvedParamCommands.push_back(PCC->getParam(Idx));
+      return;
     }
-    PCC->setParamIndex(ResolvedParamIndex);
-    if (ParamVarDocs[ResolvedParamIndex]) {
-      SourceRange ArgRange = PCC->getParamNameRange();
-      Diag(ArgRange.getBegin(), diag::warn_doc_param_duplicate)
-        << ParamName << ArgRange;
-      ParamCommandComment *PrevCommand = ParamVarDocs[ResolvedParamIndex];
-      Diag(PrevCommand->getLocation(), diag::note_doc_param_previous)
-        << PrevCommand->getParamNameRange();
+    PCC->setParamIndex(Idx, ResolvedParamIndex);
+
+    if (ResolvedParamIndex == ParamCommandComment::VarArgParamIndex) {
+      if (VarArgDocs) {
+        SourceRange ParamRange = PCC->getParamRange(Idx);
+        Diag(ParamRange.getBegin(), diag::warn_doc_param_duplicate)
+            << ParamName << ParamRange;
+        Diag(VarArgDocs->getBegin(), diag::note_doc_param_previous)
+            << *VarArgDocs;
+      } else
+        VarArgDocs = &(PCC->getParam(Idx)->Range);
+
+      return;
     }
-    ParamVarDocs[ResolvedParamIndex] = PCC;
+
+    if (const SourceRange *PrevRange = ParamVarDocs[ResolvedParamIndex]) {
+      SourceRange ParamRange = PCC->getParamRange(Idx);
+      Diag(ParamRange.getBegin(), diag::warn_doc_param_duplicate)
+          << ParamName << ParamRange;
+      Diag(PrevRange->getBegin(), diag::note_doc_param_previous) << *PrevRange;
+    } else
+      ParamVarDocs[ResolvedParamIndex] = &(PCC->getParam(Idx)->Range);
+  };
+
+  // First pass over all \\param commands: resolve all parameter names.
+  for (auto *C : FC->getBlocks()) {
+    ParamCommandComment *PCC = dyn_cast<ParamCommandComment>(C);
+    if (!PCC)
+      continue;
+
+    for (unsigned I = 0, E = PCC->getNumParams(); I != E; ++I)
+      ProcessParameter(PCC, I);
   }
 
   // Find parameter declarations that have no corresponding \\param.
   SmallVector<const ParmVarDecl *, 8> OrphanedParamDecls;
   for (unsigned i = 0, e = ParamVarDocs.size(); i != e; ++i) {
     if (!ParamVarDocs[i])
       OrphanedParamDecls.push_back(ParamVars[i]);
   }
+  bool UndocumentedVariadic = isFunctionOrMethodVariadic() && !VarArgDocs;
 
   // Second pass over unresolved \\param commands: do typo correction.
   // Suggest corrections from a set of parameter declarations that have no
   // corresponding \\param.
-  for (unsigned i = 0, e = UnresolvedParamCommands.size(); i != e; ++i) {
-    const ParamCommandComment *PCC = UnresolvedParamCommands[i];
-
-    SourceRange ArgRange = PCC->getParamNameRange();
-    StringRef ParamName = PCC->getParamNameAsWritten();
+  for (const auto *Arg : UnresolvedParamCommands) {
+    SourceRange ArgRange = Arg->Range;
+    StringRef ParamName = Arg->Text;
     Diag(ArgRange.getBegin(), diag::warn_doc_param_not_found)
         << ParamName << ArgRange;
 
     // All parameters documented -- can't suggest a correction.
-    if (OrphanedParamDecls.size() == 0)
+    if (OrphanedParamDecls.size() == 0 && !UndocumentedVariadic)
       continue;
 
-    unsigned CorrectedParamIndex = ParamCommandComment::InvalidParamIndex;
-    if (OrphanedParamDecls.size() == 1) {
-      // If one parameter is not documented then that parameter is the only
-      // possible suggestion.
-      CorrectedParamIndex = 0;
-    } else {
+    unsigned CorrectedParamIndex =
+        OrphanedParamDecls.size() == 1 && !UndocumentedVariadic
+            // If one parameter is not documented then that parameter is the
+            // only possible suggestion.
+            ? 0
             // Do typo correction.
-      CorrectedParamIndex = correctTypoInParmVarReference(ParamName,
-                                                          OrphanedParamDecls);
-    }
-    if (CorrectedParamIndex != ParamCommandComment::InvalidParamIndex) {
-      const ParmVarDecl *CorrectedPVD = OrphanedParamDecls[CorrectedParamIndex];
-      if (const IdentifierInfo *CorrectedII = CorrectedPVD->getIdentifier())
+            : correctTypoInParmVarReference(ParamName, OrphanedParamDecls);
+
+    switch (CorrectedParamIndex) {
+    case ParamCommandComment::InvalidParamIndex:
+      /* DO NOTHING */
+      break;
+
+    case ParamCommandComment::VarArgParamIndex:
+      Diag(ArgRange.getBegin(), diag::note_doc_param_name_suggestion)
+          << "..." << FixItHint::CreateReplacement(ArgRange, "...");
+
+      UndocumentedVariadic = false;
+      break;
+
+    default:
+      if (const IdentifierInfo *CorrectedII =
+              OrphanedParamDecls[CorrectedParamIndex]->getIdentifier())
         Diag(ArgRange.getBegin(), diag::note_doc_param_name_suggestion)
             << CorrectedII->getName()
             << FixItHint::CreateReplacement(ArgRange, CorrectedII->getName());
+
+      // Avoid suggesting the same parameter twice
+      OrphanedParamDecls.erase(OrphanedParamDecls.begin() +
+                               CorrectedParamIndex);
+    }
+  }
+  if (WarnUndocumentedParameters) {
+    for (const auto *OrphanedParamDecl : OrphanedParamDecls)
+      if (auto Identifier = OrphanedParamDecl->getIdentifier()) {
+        SourceLocation Loc = OrphanedParamDecl->getLocation();
+        Diag(Loc, diag::warn_doc_param_undocumented)
+            << Identifier->getName()
+            << SourceRange(Loc, OrphanedParamDecl->getEndLoc());
+      }
+    if (UndocumentedVariadic) {
+      const FunctionDecl *FD =
+          dyn_cast<FunctionDecl>(ThisDeclInfo->CurrentDecl);
+      assert(FD);
+
+      SourceLocation Loc = FD->getEllipsisLoc();
+      Diag(Loc, diag::warn_doc_param_undocumented)
+          << "..." << SourceRange(Loc, Loc.getLocWithOffset(2));
     }
   }
 }
 
 bool Sema::isFunctionDecl() {
   if (!ThisDeclInfo)
     return false;
   if (!ThisDeclInfo->IsFilled)
void SimpleTypoCorrector::addDecl(const NamedDecl *ND) {
   if (EditDistance < BestEditDistance) {
     BestEditDistance = EditDistance;
     BestDecl = ND;
     BestIndex = CurrIndex;
   }
 }
 } // end anonymous namespace
 
-unsigned Sema::correctTypoInParmVarReference(
-                                    StringRef Typo,
+unsigned
+Sema::correctTypoInParmVarReference(StringRef Typo,
                                     ArrayRef<const ParmVarDecl *> ParamVars) {
+  if (isFunctionOrMethodVariadic() &&
+      Typo.find_first_not_of('.') == StringRef::npos)
+    return ParamCommandComment::VarArgParamIndex;
+
   SimpleTypoCorrector Corrector(Typo);
   for (unsigned i = 0, e = ParamVars.size(); i != e; ++i)
     Corrector.addDecl(ParamVars[i]);
   if (Corrector.getBestDecl())
     return Corrector.getBestDeclIndex();
-  else
-    return ParamCommandComment::InvalidParamIndex;
+
 }
 
 namespace {
 bool ResolveTParamReferenceHelper(
                             StringRef Name,
                             const TemplateParameterList *TemplateParameters,
                             SmallVectorImpl<unsigned> *Position) {
   for (unsigned i = 0, e = TemplateParameters->size(); i != e; ++i) {

clang/lib/AST/JSONNodeDumper.cpp

case comments::ParamCommandComment::Out:
     JOS.attribute("direction", "out");
     break;
   case comments::ParamCommandComment::InOut:
     JOS.attribute("direction", "in,out");
     break;
   }
   attributeOnlyIfTrue("explicit", C->isDirectionExplicit());
 
-  if (C->hasParamName())
-    JOS.attribute("param", C->isParamIndexValid() ? C->getParamName(FC)
-                                                  : C->getParamNameAsWritten());
+  unsigned E = C->getNumParams();
+  if (E) {
+    llvm::json::Array Params;
+    llvm::json::Array Indexes;
+    for (unsigned I = 0; I != E; ++I) {
+      Params.push_back(C->getParamName(FC, I));
+
+      unsigned Idx = C->getParamIndex(I);
+      switch (Idx) {
+      case comments::ParamCommandComment::InvalidParamIndex:
+        Indexes.push_back("invalid");
+        break;
+
+      case comments::ParamCommandComment::VarArgParamIndex:
+        Indexes.push_back("...");
+        break;
 
-  if (C->isParamIndexValid() && !C->isVarArgParam())
-    JOS.attribute("paramIdx", C->getParamIndex());
+      default:
+        Indexes.push_back(Idx);
+        break;
+      }
+    }
+    JOS.attribute("params", std::move(Params));
+    JOS.attribute("positions", std::move(Indexes));
+  }
 }
 
 void JSONNodeDumper::visitTParamCommandComment(
     const comments::TParamCommandComment *C, const comments::FullComment *FC) {
   if (C->hasParamName())
     JOS.attribute("param", C->isPositionValid() ? C->getParamName(FC)
                                                 : C->getParamNameAsWritten());
   if (C->isPositionValid()) {

clang/lib/AST/TextNodeDumper.cpp

void TextNodeDumper::visitParamCommandComment(
   OS << " "
      << comments::ParamCommandComment::getDirectionAsString(C->getDirection());
 
   if (C->isDirectionExplicit())
     OS << " explicitly";
   else
     OS << " implicitly";
 
-  if (C->hasParamName()) {
-    if (C->isParamIndexValid())
-      OS << " Param=\"" << C->getParamName(FC) << "\"";
-    else
-      OS << " Param=\"" << C->getParamNameAsWritten() << "\"";
+  unsigned E = C->getNumParams();
+  if (E) {
+    OS << " Param=[";
+    for (unsigned I = 0; I != E; ++I) {
+      if (I != 0)
+        OS << ", ";
+      OS << C->getParamName(FC, I);
     }
+    OS << "]";
+
+    OS << " ParamIndex=[";
+    for (unsigned I = 0; I != E; ++I) {
+      if (I != 0)
+        OS << ", ";
+
+      unsigned Idx = C->getParamIndex(I);
+      switch (Idx) {
+      case comments::ParamCommandComment::InvalidParamIndex:
+        OS << "invalid";
+        break;
 
-  if (C->isParamIndexValid() && !C->isVarArgParam())
-    OS << " ParamIndex=" << C->getParamIndex();
+      case comments::ParamCommandComment::VarArgParamIndex:
+        OS << "...";
+        break;
+
+      default:
+        OS << Idx;
+        break;
+      }
+    }
+    OS << "]";
+  }
 }
 
 void TextNodeDumper::visitTParamCommandComment(
     const comments::TParamCommandComment *C, const comments::FullComment *FC) {
   if (C->hasParamName()) {
     if (C->isPositionValid())
       OS << " Param=\"" << C->getParamName(FC) << "\"";
     else

clang/lib/Index/CommentToXML.cpp

 namespace {
 
 /// This comparison will sort parameters with valid index by index, then vararg
 /// parameters, and invalid (unresolved) parameters last.
 class ParamCommandCommentCompareIndex {
 public:
   bool operator()(const ParamCommandComment *LHS,
                   const ParamCommandComment *RHS) const {
-    unsigned LHSIndex = UINT_MAX;
-    unsigned RHSIndex = UINT_MAX;
+    unsigned LHS_I = 0;
+    unsigned LHS_E = LHS->getNumParams();
+    unsigned RHS_I = 0;
+    unsigned RHS_E = LHS->getNumParams();
+
+    for (; LHS_I != LHS_E && RHS_I != RHS_E; ++LHS_I, ++RHS_I) {
+      unsigned LHSIndex = LHS->getParamIndex(LHS_I);
+      unsigned RHSIndex = RHS->getParamIndex(RHS_I);
 
-    if (LHS->isParamIndexValid()) {
-      if (LHS->isVarArgParam())
-        LHSIndex = UINT_MAX - 1;
-      else
-        LHSIndex = LHS->getParamIndex();
-    }
-    if (RHS->isParamIndexValid()) {
-      if (RHS->isVarArgParam())
-        RHSIndex = UINT_MAX - 1;
-      else
-        RHSIndex = RHS->getParamIndex();
+      if (LHSIndex < RHSIndex)
+        return true;
+      if (LHSIndex > RHSIndex)
+        return false;
     }
-    return LHSIndex < RHSIndex;
+
+    return LHS_I == LHS_E && RHS_I != RHS_E;
   }
 };
 
 /// This comparison will sort template parameters in the following order:
 /// \li real template parameters (depth = 1) in index order;
 /// \li all other names (depth > 1);
 /// \li unresolved names.
 class TParamCommandCommentComparePosition {
case Comment::BlockCommandCommentKind: {
         break;
       }
       MiscBlocks.push_back(BCC);
       break;
     }
 
     case Comment::ParamCommandCommentKind: {
       const ParamCommandComment *PCC = cast<ParamCommandComment>(Child);
-      if (!PCC->hasParamName())
+      if (PCC->getNumParams() == 0)
         break;
 
       if (!PCC->isDirectionExplicit() && !PCC->hasNonWhitespaceParagraph())
         break;
 
       Params.push_back(PCC);
       break;
     }
if (Info->IsReturnsCommand) {
     return;
   }
   // We don't know anything about this command.  Just render the paragraph.
   visit(C->getParagraph());
 }
 
 void CommentASTToHTMLConverter::visitParamCommandComment(
                                   const ParamCommandComment *C) {
-  if (C->isParamIndexValid()) {
-    if (C->isVarArgParam()) {
-      Result << "<dt class=\"param-name-index-vararg\">";
-      appendToResultWithHTMLEscaping(C->getParamNameAsWritten());
-    } else {
-      Result << "<dt class=\"param-name-index-"
-             << C->getParamIndex()
-             << "\">";
-      appendToResultWithHTMLEscaping(C->getParamName(FC));
+
+  unsigned E = C->getNumParams();
+  if (E == 0)
+    return;
+
+  SmallString<16> ID;
+  SmallString<128> Identifier;
+  for (unsigned I = 0; I != E; ++I) {
+    unsigned Idx = C->getParamIndex(I);
+    switch (Idx) {
+    case ParamCommandComment::InvalidParamIndex:
+      ID += "-invalid";
+      break;
+
+    case ParamCommandComment::VarArgParamIndex:
+      ID += "-vararg";
+      break;
+
+    default:
+      ID += '-';
+      ID += std::to_string(Idx);
+      break;
     }
-  } else {
-    Result << "<dt class=\"param-name-index-invalid\">";
-    appendToResultWithHTMLEscaping(C->getParamNameAsWritten());
+    if (!Identifier.empty())
+      Identifier += ",";
+    Identifier += C->getParamName(FC, I);
   }
-  Result << "</dt>";
 
-  if (C->isParamIndexValid()) {
-    if (C->isVarArgParam())
-      Result << "<dd class=\"param-descr-index-vararg\">";
-    else
-      Result << "<dd class=\"param-descr-index-"
-             << C->getParamIndex()
-             << "\">";
-  } else
-    Result << "<dd class=\"param-descr-index-invalid\">";
+  Result << "<dt class=\"param-name-index" << ID << "\">";
+  appendToResultWithHTMLEscaping(Identifier);
+  Result << "</dt>";
 
+  Result << "<dd class=\"param-descr-index" << ID << "\">";
   visitNonStandaloneParagraphComment(C->getParagraph());
   Result << "</dd>";
 }
 
 void CommentASTToHTMLConverter::visitTParamCommandComment(
                                   const TParamCommandComment *C) {
   if (C->isPositionValid()) {
     if (C->getDepth() == 1)
default:
     break;
   }
 
   appendParagraphCommentWithKind(C->getParagraph(), ParagraphKind);
 }
 
 void CommentASTToXMLConverter::visitParamCommandComment(
     const ParamCommandComment *C) {
-  Result << "<Parameter><Name>";
-  appendToResultWithXMLEscaping(C->isParamIndexValid()
-                                    ? C->getParamName(FC)
-                                    : C->getParamNameAsWritten());
+
+  Result << "<Parameter>";
+  unsigned E = C->getNumParams();
+  if (E) {
+    Result << "<Identifiers>";
+    for (unsigned I = 0; I != E; ++I) {
+      Result << "<Identifier>";
+
+      Result << "<Name>";
+      appendToResultWithXMLEscaping(C->getParamName(FC, I));
       Result << "</Name>";
 
-  if (C->isParamIndexValid()) {
-    if (C->isVarArgParam())
+      unsigned Idx = C->getParamIndex(I);
+      switch (Idx) {
+      case comments::ParamCommandComment::InvalidParamIndex:
+        /* DO NOTHING */
+        break;
+
+      case comments::ParamCommandComment::VarArgParamIndex:
         Result << "<IsVarArg />";
-    else
-      Result << "<Index>" << C->getParamIndex() << "</Index>";
+        break;
+
+      default:
+        Result << "<Index>" << Idx << "</Index>";
+        break;
+      }
+
+      Result << "</Identifier>";
+    }
+    Result << "</Identifiers>";
   }
 
   Result << "<Direction isExplicit=\"" << C->isDirectionExplicit() << "\">";
   switch (C->getDirection()) {
   case ParamCommandComment::In:
     Result << "in";
     break;
   case ParamCommandComment::Out:

clang/test/AST/ast-dump-comment-json.cpp

 int Test_HTMLTagComment;
 
 /// \verbatim
 /// Aaa
 /// \endverbatim
 int Test_VerbatimBlockComment;
 
 /// \param ... More arguments
 template<typename T>
-void Test_TemplatedFunctionVariadic(int arg, ...);
+void Test_TemplatedFunctionVariadic(...);
+
+/// \param aaa xxx
+/// \param bbb Invalid argument
+/// \param ... More arguments
+template<typename T>
+void Test_TemplatedFunctionParamAndVariadic(int aaa, ...);
+
+/// \param aaa,bbb,... xxx
+template<typename T>
+void Test_TemplatedFunctionParamAndVariadic2(int aaa, ...);
+
 
 // NOTE: CHECK lines have been autogenerated by gen_ast_dump_json_test.py
 // using --filters=FullComment
 
 
 // CHECK:  "kind": "FullComment",
 // CHECK-NEXT:  "loc": {
 // CHECK-NEXT:   "offset": 72,
 // CHECK-NEXT:   "line": 3,

 // CHECK-NEXT:       }
 // CHECK-NEXT:      ]
 // CHECK-NEXT:     }
 // CHECK-NEXT:    ]
 // CHECK-NEXT:   }
 // CHECK-NEXT:  ]
 // CHECK-NEXT: }
 
 
 // CHECK:  "kind": "FullComment",
 // CHECK-NEXT:  "loc": {
 // CHECK-NEXT:   "offset": 197,
 // CHECK-NEXT:   "line": 15,
 // CHECK-NEXT:   "col": 4,
 // CHECK-NEXT:   "tokLen": 0
 // CHECK-NEXT:  },
 // CHECK-NEXT:  "range": {

 // CHECK-NEXT:     "end": {
 // CHECK-NEXT:      "offset": 216,
 // CHECK-NEXT:      "line": 16,
 // CHECK-NEXT:      "col": 4,
 // CHECK-NEXT:      "tokLen": 0
 // CHECK-NEXT:     }
 // CHECK-NEXT:    },
 // CHECK-NEXT:    "direction": "in",
-// CHECK-NEXT:    "param": "Aaa",
-// CHECK-NEXT:    "paramIdx": 0,
+// CHECK-NEXT:    "params": [
+// CHECK-NEXT:     "Aaa"
+// CHECK-NEXT:    ],
+// CHECK-NEXT:    "positions": [
+// CHECK-NEXT:     0
+// CHECK-NEXT:    ],
 // CHECK-NEXT:    "inner": [
 // CHECK-NEXT:     {
 // CHECK-NEXT:      "id": "0x{{.*}}",
 // CHECK-NEXT:      "kind": "ParagraphComment",
 // CHECK-NEXT:      "loc": {
 // CHECK-NEXT:       "offset": 208,
 // CHECK-NEXT:       "line": 15,
 // CHECK-NEXT:       "col": 15,

 // CHECK-NEXT:     "end": {
 // CHECK-NEXT:      "offset": 239,
 // CHECK-NEXT:      "col": 27,
 // CHECK-NEXT:      "tokLen": 1
 // CHECK-NEXT:     }
 // CHECK-NEXT:    },
 // CHECK-NEXT:    "direction": "in,out",
 // CHECK-NEXT:    "explicit": true,
-// CHECK-NEXT:    "param": "Bbb",
-// CHECK-NEXT:    "paramIdx": 1,
+// CHECK-NEXT:    "params": [
+// CHECK-NEXT:     "Bbb"
+// CHECK-NEXT:    ],
+// CHECK-NEXT:    "positions": [
+// CHECK-NEXT:     1
+// CHECK-NEXT:    ],
 // CHECK-NEXT:    "inner": [
 // CHECK-NEXT:     {
 // CHECK-NEXT:      "id": "0x{{.*}}",
 // CHECK-NEXT:      "kind": "ParagraphComment",
 // CHECK-NEXT:      "loc": {
 // CHECK-NEXT:       "offset": 236,
 // CHECK-NEXT:       "col": 24,
 // CHECK-NEXT:       "tokLen": 0

 // CHECK-NEXT:       }
 // CHECK-NEXT:      ]
 // CHECK-NEXT:     }
 // CHECK-NEXT:    ]
 // CHECK-NEXT:   }
 // CHECK-NEXT:  ]
 // CHECK-NEXT: }
 
 
 // CHECK:  "kind": "FullComment",
 // CHECK-NEXT:  "loc": {
 // CHECK-NEXT:   "offset": 294,
 // CHECK-NEXT:   "line": 19,
 // CHECK-NEXT:   "col": 4,
 // CHECK-NEXT:   "tokLen": 0
 // CHECK-NEXT:  },
 // CHECK-NEXT:  "range": {

 // CHECK-NEXT:      },
 // CHECK-NEXT:      "text": " Aaa"
 // CHECK-NEXT:     }
 // CHECK-NEXT:    ]
 // CHECK-NEXT:   }
 // CHECK-NEXT:  ]
 // CHECK-NEXT: }
 
 
 // CHECK:  "kind": "FullComment",
 // CHECK-NEXT:  "loc": {
 // CHECK-NEXT:   "offset": 537,
 // CHECK-NEXT:   "line": 34,
 // CHECK-NEXT:   "col": 4,
 // CHECK-NEXT:   "tokLen": 0
 // CHECK-NEXT:  },
 // CHECK-NEXT:  "range": {

 // CHECK-NEXT:     },
 // CHECK-NEXT:     "end": {
 // CHECK-NEXT:      "offset": 562,
 // CHECK-NEXT:      "col": 29,
 // CHECK-NEXT:      "tokLen": 1
 // CHECK-NEXT:     }
 // CHECK-NEXT:    },
 // CHECK-NEXT:    "direction": "in",
-// CHECK-NEXT:    "param": "...",
+// CHECK-NEXT:    "params": [
+// CHECK-NEXT:     "..."
+// CHECK-NEXT:    ],
+// CHECK-NEXT:    "positions": [
+// CHECK-NEXT:     "..."
+// CHECK-NEXT:    ],
 // CHECK-NEXT:    "inner": [
 // CHECK-NEXT:     {
 // CHECK-NEXT:      "id": "0x{{.*}}",
 // CHECK-NEXT:      "kind": "ParagraphComment",
 // CHECK-NEXT:      "loc": {
 // CHECK-NEXT:       "offset": 548,
 // CHECK-NEXT:       "col": 15,
 // CHECK-NEXT:       "tokLen": 0

 // CHECK-NEXT:       }
 // CHECK-NEXT:      ]
 // CHECK-NEXT:     }
 // CHECK-NEXT:    ]
 // CHECK-NEXT:   }
 // CHECK-NEXT:  ]
 // CHECK-NEXT: }
 
 
 // CHECK:  "kind": "FullComment",
 // CHECK-NEXT:  "loc": {
 // CHECK-NEXT:   "offset": 537,
 // CHECK-NEXT:   "col": 4,
 // CHECK-NEXT:   "tokLen": 0
 // CHECK-NEXT:  },
 // CHECK-NEXT:  "range": {
 // CHECK-NEXT:   "begin": {

 // CHECK-NEXT:     },
 // CHECK-NEXT:     "end": {
 // CHECK-NEXT:      "offset": 562,
 // CHECK-NEXT:      "col": 29,
 // CHECK-NEXT:      "tokLen": 1
 // CHECK-NEXT:     }
 // CHECK-NEXT:    },
 // CHECK-NEXT:    "direction": "in",
-// CHECK-NEXT:    "param": "...",
+// CHECK-NEXT:    "params": [
+// CHECK-NEXT:     "..."
+// CHECK-NEXT:    ],
+// CHECK-NEXT:    "positions": [
+// CHECK-NEXT:     "..."
+// CHECK-NEXT:    ],
 // CHECK-NEXT:    "inner": [
 // CHECK-NEXT:     {
 // CHECK-NEXT:      "id": "0x{{.*}}",
 // CHECK-NEXT:      "kind": "ParagraphComment",
 // CHECK-NEXT:      "loc": {
 // CHECK-NEXT:       "offset": 548,
 // CHECK-NEXT:       "col": 15,
 // CHECK-NEXT:       "tokLen": 0

 // CHECK-NEXT:        "text": " More arguments"
 // CHECK-NEXT:       }
 // CHECK-NEXT:      ]
 // CHECK-NEXT:     }
 // CHECK-NEXT:    ]
 // CHECK-NEXT:   }
 // CHECK-NEXT:  ]
 // CHECK-NEXT: }
+
+
+// CHECK:  "kind": "FullComment",
+// CHECK-NEXT:  "loc": {
+// CHECK-NEXT:   "offset": 631,
+// CHECK-NEXT:   "line": 38,
+// CHECK-NEXT:   "col": 4,
+// CHECK-NEXT:   "tokLen": 0
+// CHECK-NEXT:  },
+// CHECK-NEXT:  "range": {
+// CHECK-NEXT:   "begin": {
+// CHECK-NEXT:    "offset": 631,
+// CHECK-NEXT:    "col": 4,
+// CHECK-NEXT:    "tokLen": 0
+// CHECK-NEXT:   },
+// CHECK-NEXT:   "end": {
+// CHECK-NEXT:    "offset": 707,
+// CHECK-NEXT:    "line": 40,
+// CHECK-NEXT:    "col": 29,
+// CHECK-NEXT:    "tokLen": 1
+// CHECK-NEXT:   }
+// CHECK-NEXT:  },
+// CHECK-NEXT:  "inner": [
+// CHECK-NEXT:   {
+// CHECK-NEXT:    "id": "0x{{.*}}",
+// CHECK-NEXT:    "kind": "ParagraphComment",
+// CHECK-NEXT:    "loc": {
+// CHECK-NEXT:     "offset": 631,
+// CHECK-NEXT:     "line": 38,
+// CHECK-NEXT:     "col": 4,
+// CHECK-NEXT:     "tokLen": 0
+// CHECK-NEXT:    },
+// CHECK-NEXT:    "range": {
+// CHECK-NEXT:     "begin": {
+// CHECK-NEXT:      "offset": 631,
+// CHECK-NEXT:      "col": 4,
+// CHECK-NEXT:      "tokLen": 0
+// CHECK-NEXT:     },
+// CHECK-NEXT:     "end": {
+// CHECK-NEXT:      "offset": 631,
+// CHECK-NEXT:      "col": 4,
+// CHECK-NEXT:      "tokLen": 0
+// CHECK-NEXT:     }
+// CHECK-NEXT:    },
+// CHECK-NEXT:    "inner": [
+// CHECK-NEXT:     {
+// CHECK-NEXT:      "id": "0x{{.*}}",
+// CHECK-NEXT:      "kind": "TextComment",
+// CHECK-NEXT:      "loc": {
+// CHECK-NEXT:       "offset": 631,
+// CHECK-NEXT:       "col": 4,
+// CHECK-NEXT:       "tokLen": 0
+// CHECK-NEXT:      },
+// CHECK-NEXT:      "range": {
+// CHECK-NEXT:       "begin": {
+// CHECK-NEXT:        "offset": 631,
+// CHECK-NEXT:        "col": 4,
+// CHECK-NEXT:        "tokLen": 0
+// CHECK-NEXT:       },
+// CHECK-NEXT:       "end": {
+// CHECK-NEXT:        "offset": 631,
+// CHECK-NEXT:        "col": 4,
+// CHECK-NEXT:        "tokLen": 0
+// CHECK-NEXT:       }
+// CHECK-NEXT:      },
+// CHECK-NEXT:      "text": " "
+// CHECK-NEXT:     }
+// CHECK-NEXT:    ]
+// CHECK-NEXT:   },
+// CHECK-NEXT:   {
+// CHECK-NEXT:    "id": "0x{{.*}}",
+// CHECK-NEXT:    "kind": "ParamCommandComment",
+// CHECK-NEXT:    "loc": {
+// CHECK-NEXT:     "offset": 633,
+// CHECK-NEXT:     "col": 6,
+// CHECK-NEXT:     "tokLen": 5
+// CHECK-NEXT:    },
+// CHECK-NEXT:    "range": {
+// CHECK-NEXT:     "begin": {
+// CHECK-NEXT:      "offset": 632,
+// CHECK-NEXT:      "col": 5,
+// CHECK-NEXT:      "tokLen": 1
+// CHECK-NEXT:     },
+// CHECK-NEXT:     "end": {
+// CHECK-NEXT:      "offset": 650,
+// CHECK-NEXT:      "line": 39,
+// CHECK-NEXT:      "col": 4,
+// CHECK-NEXT:      "tokLen": 0
+// CHECK-NEXT:     }
+// CHECK-NEXT:    },
+// CHECK-NEXT:    "direction": "in",
+// CHECK-NEXT:    "params": [
+// CHECK-NEXT:     "aaa"
+// CHECK-NEXT:    ],
+// CHECK-NEXT:    "positions": [
+// CHECK-NEXT:     0
+// CHECK-NEXT:    ],
+// CHECK-NEXT:    "inner": [
+// CHECK-NEXT:     {
+// CHECK-NEXT:      "id": "0x{{.*}}",
+// CHECK-NEXT:      "kind": "ParagraphComment",
+// CHECK-NEXT:      "loc": {
+// CHECK-NEXT:       "offset": 642,
+// CHECK-NEXT:       "line": 38,
+// CHECK-NEXT:       "col": 15,
+// CHECK-NEXT:       "tokLen": 0
+// CHECK-NEXT:      },
+// CHECK-NEXT:      "range": {
+// CHECK-NEXT:       "begin": {
+// CHECK-NEXT:        "offset": 642,
+// CHECK-NEXT:        "col": 15,
+// CHECK-NEXT:        "tokLen": 0
+// CHECK-NEXT:       },
+// CHECK-NEXT:       "end": {
+// CHECK-NEXT:        "offset": 650,
+// CHECK-NEXT:        "line": 39,
+// CHECK-NEXT:        "col": 4,
+// CHECK-NEXT:        "tokLen": 0
+// CHECK-NEXT:       }
+// CHECK-NEXT:      },
+// CHECK-NEXT:      "inner": [
+// CHECK-NEXT:       {
+// CHECK-NEXT:        "id": "0x{{.*}}",
+// CHECK-NEXT:        "kind": "TextComment",
+// CHECK-NEXT:        "loc": {
+// CHECK-NEXT:         "offset": 642,
+// CHECK-NEXT:         "line": 38,
+// CHECK-NEXT:         "col": 15,
+// CHECK-NEXT:         "tokLen": 0
+// CHECK-NEXT:        },
+// CHECK-NEXT:        "range": {
+// CHECK-NEXT:         "begin": {
+// CHECK-NEXT:          "offset": 642,
+// CHECK-NEXT:          "col": 15,
+// CHECK-NEXT:          "tokLen": 0
+// CHECK-NEXT:         },
+// CHECK-NEXT:         "end": {
+// CHECK-NEXT:          "offset": 645,
+// CHECK-NEXT:          "col": 18,
+// CHECK-NEXT:          "tokLen": 1
+// CHECK-NEXT:         }
+// CHECK-NEXT:        },
+// CHECK-NEXT:        "text": " xxx"
+// CHECK-NEXT:       },
+// CHECK-NEXT:       {
+// CHECK-NEXT:        "id": "0x{{.*}}",
+// CHECK-NEXT:        "kind": "TextComment",
+// CHECK-NEXT:        "loc": {
+// CHECK-NEXT:         "offset": 650,
+// CHECK-NEXT:         "line": 39,
+// CHECK-NEXT:         "col": 4,
+// CHECK-NEXT:         "tokLen": 0
+// CHECK-NEXT:        },
+// CHECK-NEXT:        "range": {
+// CHECK-NEXT:         "begin": {
+// CHECK-NEXT:          "offset": 650,
+// CHECK-NEXT:          "col": 4,
+// CHECK-NEXT:          "tokLen": 0
+// CHECK-NEXT:         },
+// CHECK-NEXT:         "end": {
+// CHECK-NEXT:          "offset": 650,
+// CHECK-NEXT:          "col": 4,
+// CHECK-NEXT:          "tokLen": 0
+// CHECK-NEXT:         }
+// CHECK-NEXT:        },
+// CHECK-NEXT:        "text": " "
+// CHECK-NEXT:       }
+// CHECK-NEXT:      ]
+// CHECK-NEXT:     }
+// CHECK-NEXT:    ]
+// CHECK-NEXT:   },
+// CHECK-NEXT:   {
+// CHECK-NEXT:    "id": "0x{{.*}}",
+// CHECK-NEXT:    "kind": "ParamCommandComment",
+// CHECK-NEXT:    "loc": {
+// CHECK-NEXT:     "offset": 652,
+// CHECK-NEXT:     "col": 6,
+// CHECK-NEXT:     "tokLen": 5
+// CHECK-NEXT:    },
+// CHECK-NEXT:    "range": {
+// CHECK-NEXT:     "begin": {
+// CHECK-NEXT:      "offset": 651,
+// CHECK-NEXT:      "col": 5,
+// CHECK-NEXT:      "tokLen": 1
+// CHECK-NEXT:     },
+// CHECK-NEXT:     "end": {
+// CHECK-NEXT:      "offset": 682,
+// CHECK-NEXT:      "line": 40,
+// CHECK-NEXT:      "col": 4,
+// CHECK-NEXT:      "tokLen": 0
+// CHECK-NEXT:     }
+// CHECK-NEXT:    },
+// CHECK-NEXT:    "direction": "in",
+// CHECK-NEXT:    "params": [
+// CHECK-NEXT:     "bbb"
+// CHECK-NEXT:    ],
+// CHECK-NEXT:    "positions": [
+// CHECK-NEXT:     "invalid"
+// CHECK-NEXT:    ],
+// CHECK-NEXT:    "inner": [
+// CHECK-NEXT:     {
+// CHECK-NEXT:      "id": "0x{{.*}}",
+// CHECK-NEXT:      "kind": "ParagraphComment",
+// CHECK-NEXT:      "loc": {
+// CHECK-NEXT:       "offset": 661,
+// CHECK-NEXT:       "line": 39,
+// CHECK-NEXT:       "col": 15,
+// CHECK-NEXT:       "tokLen": 0
+// CHECK-NEXT:      },
+// CHECK-NEXT:      "range": {
+// CHECK-NEXT:       "begin": {
+// CHECK-NEXT:        "offset": 661,
+// CHECK-NEXT:        "col": 15,
+// CHECK-NEXT:        "tokLen": 0
+// CHECK-NEXT:       },
+// CHECK-NEXT:       "end": {
+// CHECK-NEXT:        "offset": 682,
+// CHECK-NEXT:        "line": 40,
+// CHECK-NEXT:        "col": 4,
+// CHECK-NEXT:        "tokLen": 0
+// CHECK-NEXT:       }
+// CHECK-NEXT:      },
+// CHECK-NEXT:      "inner": [
+// CHECK-NEXT:       {
+// CHECK-NEXT:        "id": "0x{{.*}}",
+// CHECK-NEXT:        "kind": "TextComment",
+// CHECK-NEXT:        "loc": {
+// CHECK-NEXT:         "offset": 661,
+// CHECK-NEXT:         "line": 39,
+// CHECK-NEXT:         "col": 15,
+// CHECK-NEXT:         "tokLen": 0
+// CHECK-NEXT:        },
+// CHECK-NEXT:        "range": {
+// CHECK-NEXT:         "begin": {
+// CHECK-NEXT:          "offset": 661,
+// CHECK-NEXT:          "col": 15,
+// CHECK-NEXT:          "tokLen": 0
+// CHECK-NEXT:         },
+// CHECK-NEXT:         "end": {
+// CHECK-NEXT:          "offset": 677,
+// CHECK-NEXT:          "col": 31,
+// CHECK-NEXT:          "tokLen": 1
+// CHECK-NEXT:         }
+// CHECK-NEXT:        },
+// CHECK-NEXT:        "text": " Invalid argument"
+// CHECK-NEXT:       },
+// CHECK-NEXT:       {
+// CHECK-NEXT:        "id": "0x{{.*}}",
+// CHECK-NEXT:        "kind": "TextComment",
+// CHECK-NEXT:        "loc": {
+// CHECK-NEXT:         "offset": 682,
+// CHECK-NEXT:         "line": 40,
+// CHECK-NEXT:         "col": 4,
+// CHECK-NEXT:         "tokLen": 0
+// CHECK-NEXT:        },
+// CHECK-NEXT:        "range": {
+// CHECK-NEXT:         "begin": {
+// CHECK-NEXT:          "offset": 682,
+// CHECK-NEXT:          "col": 4,
+// CHECK-NEXT:          "tokLen": 0
+// CHECK-NEXT:         },
+// CHECK-NEXT:         "end": {
+// CHECK-NEXT:          "offset": 682,
+// CHECK-NEXT:          "col": 4,
+// CHECK-NEXT:          "tokLen": 0
+// CHECK-NEXT:         }
+// CHECK-NEXT:        },
+// CHECK-NEXT:        "text": " "
+// CHECK-NEXT:       }
+// CHECK-NEXT:      ]
+// CHECK-NEXT:     }
+// CHECK-NEXT:    ]
+// CHECK-NEXT:   },
+// CHECK-NEXT:   {
+// CHECK-NEXT:    "id": "0x{{.*}}",
+// CHECK-NEXT:    "kind": "ParamCommandComment",
+// CHECK-NEXT:    "loc": {
+// CHECK-NEXT:     "offset": 684,
+// CHECK-NEXT:     "col": 6,
+// CHECK-NEXT:     "tokLen": 5
+// CHECK-NEXT:    },
+// CHECK-NEXT:    "range": {
+// CHECK-NEXT:     "begin": {
+// CHECK-NEXT:      "offset": 683,
+// CHECK-NEXT:      "col": 5,
+// CHECK-NEXT:      "tokLen": 1
+// CHECK-NEXT:     },
+// CHECK-NEXT:     "end": {
+// CHECK-NEXT:      "offset": 707,
+// CHECK-NEXT:      "col": 29,
+// CHECK-NEXT:      "tokLen": 1
+// CHECK-NEXT:     }
+// CHECK-NEXT:    },
+// CHECK-NEXT:    "direction": "in",
+// CHECK-NEXT:    "params": [
+// CHECK-NEXT:     "..."
+// CHECK-NEXT:    ],
+// CHECK-NEXT:    "positions": [
+// CHECK-NEXT:     "..."
+// CHECK-NEXT:    ],
+// CHECK-NEXT:    "inner": [
+// CHECK-NEXT:     {
+// CHECK-NEXT:      "id": "0x{{.*}}",
+// CHECK-NEXT:      "kind": "ParagraphComment",
+// CHECK-NEXT:      "loc": {
+// CHECK-NEXT:       "offset": 693,
+// CHECK-NEXT:       "col": 15,
+// CHECK-NEXT:       "tokLen": 0
+// CHECK-NEXT:      },
+// CHECK-NEXT:      "range": {
+// CHECK-NEXT:       "begin": {
+// CHECK-NEXT:        "offset": 693,
+// CHECK-NEXT:        "col": 15,
+// CHECK-NEXT:        "tokLen": 0
+// CHECK-NEXT:       },
+// CHECK-NEXT:       "end": {
+// CHECK-NEXT:        "offset": 707,
+// CHECK-NEXT:        "col": 29,
+// CHECK-NEXT:        "tokLen": 1
+// CHECK-NEXT:       }
+// CHECK-NEXT:      },
+// CHECK-NEXT:      "inner": [
+// CHECK-NEXT:       {
+// CHECK-NEXT:        "id": "0x{{.*}}",
+// CHECK-NEXT:        "kind": "TextComment",
+// CHECK-NEXT:        "loc": {
+// CHECK-NEXT:         "offset": 693,
+// CHECK-NEXT:         "col": 15,
+// CHECK-NEXT:         "tokLen": 0
+// CHECK-NEXT:        },
+// CHECK-NEXT:        "range": {
+// CHECK-NEXT:         "begin": {
+// CHECK-NEXT:          "offset": 693,
+// CHECK-NEXT:          "col": 15,
+// CHECK-NEXT:          "tokLen": 0
+// CHECK-NEXT:         },
+// CHECK-NEXT:         "end": {
+// CHECK-NEXT:          "offset": 707,
+// CHECK-NEXT:          "col": 29,
+// CHECK-NEXT:          "tokLen": 1
+// CHECK-NEXT:         }
+// CHECK-NEXT:        },
+// CHECK-NEXT:        "text": " More arguments"
+// CHECK-NEXT:       }
+// CHECK-NEXT:      ]
+// CHECK-NEXT:     }
+// CHECK-NEXT:    ]
+// CHECK-NEXT:   }
+// CHECK-NEXT:  ]
+// CHECK-NEXT: }
+
+
+// CHECK:  "kind": "FullComment",
+// CHECK-NEXT:  "loc": {
+// CHECK-NEXT:   "offset": 631,
+// CHECK-NEXT:   "line": 38,
+// CHECK-NEXT:   "col": 4,
+// CHECK-NEXT:   "tokLen": 0
+// CHECK-NEXT:  },
+// CHECK-NEXT:  "range": {
+// CHECK-NEXT:   "begin": {
+// CHECK-NEXT:    "offset": 631,
+// CHECK-NEXT:    "col": 4,
+// CHECK-NEXT:    "tokLen": 0
+// CHECK-NEXT:   },
+// CHECK-NEXT:   "end": {
+// CHECK-NEXT:    "offset": 707,
+// CHECK-NEXT:    "line": 40,
+// CHECK-NEXT:    "col": 29,
+// CHECK-NEXT:    "tokLen": 1
+// CHECK-NEXT:   }
+// CHECK-NEXT:  },
+// CHECK-NEXT:  "inner": [
+// CHECK-NEXT:   {
+// CHECK-NEXT:    "id": "0x{{.*}}",
+// CHECK-NEXT:    "kind": "ParagraphComment",
+// CHECK-NEXT:    "loc": {
+// CHECK-NEXT:     "offset": 631,
+// CHECK-NEXT:     "line": 38,
+// CHECK-NEXT:     "col": 4,
+// CHECK-NEXT:     "tokLen": 0
+// CHECK-NEXT:    },
+// CHECK-NEXT:    "range": {
+// CHECK-NEXT:     "begin": {
+// CHECK-NEXT:      "offset": 631,
+// CHECK-NEXT:      "col": 4,
+// CHECK-NEXT:      "tokLen": 0
+// CHECK-NEXT:     },
+// CHECK-NEXT:     "end": {
+// CHECK-NEXT:      "offset": 631,
+// CHECK-NEXT:      "col": 4,
+// CHECK-NEXT:      "tokLen": 0
+// CHECK-NEXT:     }
+// CHECK-NEXT:    },
+// CHECK-NEXT:    "inner": [
+// CHECK-NEXT:     {
+// CHECK-NEXT:      "id": "0x{{.*}}",
+// CHECK-NEXT:      "kind": "TextComment",
+// CHECK-NEXT:      "loc": {
+// CHECK-NEXT:       "offset": 631,
+// CHECK-NEXT:       "col": 4,
+// CHECK-NEXT:       "tokLen": 0
+// CHECK-NEXT:      },
+// CHECK-NEXT:      "range": {
+// CHECK-NEXT:       "begin": {
+// CHECK-NEXT:        "offset": 631,
+// CHECK-NEXT:        "col": 4,
+// CHECK-NEXT:        "tokLen": 0
+// CHECK-NEXT:       },
+// CHECK-NEXT:       "end": {
+// CHECK-NEXT:        "offset": 631,
+// CHECK-NEXT:        "col": 4,
+// CHECK-NEXT:        "tokLen": 0
+// CHECK-NEXT:       }
+// CHECK-NEXT:      },
+// CHECK-NEXT:      "text": " "
+// CHECK-NEXT:     }
+// CHECK-NEXT:    ]
+// CHECK-NEXT:   },
+// CHECK-NEXT:   {
+// CHECK-NEXT:    "id": "0x{{.*}}",
+// CHECK-NEXT:    "kind": "ParamCommandComment",
+// CHECK-NEXT:    "loc": {
+// CHECK-NEXT:     "offset": 633,
+// CHECK-NEXT:     "col": 6,
+// CHECK-NEXT:     "tokLen": 5
+// CHECK-NEXT:    },
+// CHECK-NEXT:    "range": {
+// CHECK-NEXT:     "begin": {
+// CHECK-NEXT:      "offset": 632,
+// CHECK-NEXT:      "col": 5,
+// CHECK-NEXT:      "tokLen": 1
+// CHECK-NEXT:     },
+// CHECK-NEXT:     "end": {
+// CHECK-NEXT:      "offset": 650,
+// CHECK-NEXT:      "line": 39,
+// CHECK-NEXT:      "col": 4,
+// CHECK-NEXT:      "tokLen": 0
+// CHECK-NEXT:     }
+// CHECK-NEXT:    },
+// CHECK-NEXT:    "direction": "in",
+// CHECK-NEXT:    "params": [
+// CHECK-NEXT:     "aaa"
+// CHECK-NEXT:    ],
+// CHECK-NEXT:    "positions": [
+// CHECK-NEXT:     0
+// CHECK-NEXT:    ],
+// CHECK-NEXT:    "inner": [
+// CHECK-NEXT:     {
+// CHECK-NEXT:      "id": "0x{{.*}}",
+// CHECK-NEXT:      "kind": "ParagraphComment",
+// CHECK-NEXT:      "loc": {
+// CHECK-NEXT:       "offset": 642,
+// CHECK-NEXT:       "line": 38,
+// CHECK-NEXT:       "col": 15,
+// CHECK-NEXT:       "tokLen": 0
+// CHECK-NEXT:      },
+// CHECK-NEXT:      "range": {
+// CHECK-NEXT:       "begin": {
+// CHECK-NEXT:        "offset": 642,
+// CHECK-NEXT:        "col": 15,
+// CHECK-NEXT:        "tokLen": 0
+// CHECK-NEXT:       },
+// CHECK-NEXT:       "end": {
+// CHECK-NEXT:        "offset": 650,
+// CHECK-NEXT:        "line": 39,
+// CHECK-NEXT:        "col": 4,
+// CHECK-NEXT:        "tokLen": 0
+// CHECK-NEXT:       }
+// CHECK-NEXT:      },
+// CHECK-NEXT:      "inner": [
+// CHECK-NEXT:       {
+// CHECK-NEXT:        "id": "0x{{.*}}",
+// CHECK-NEXT:        "kind": "TextComment",
+// CHECK-NEXT:        "loc": {
+// CHECK-NEXT:         "offset": 642,
+// CHECK-NEXT:         "line": 38,
+// CHECK-NEXT:         "col": 15,
+// CHECK-NEXT:         "tokLen": 0
+// CHECK-NEXT:        },
+// CHECK-NEXT:        "range": {
+// CHECK-NEXT:         "begin": {
+// CHECK-NEXT:          "offset": 642,
+// CHECK-NEXT:          "col": 15,
+// CHECK-NEXT:          "tokLen": 0
+// CHECK-NEXT:         },
+// CHECK-NEXT:         "end": {
+// CHECK-NEXT:          "offset": 645,
+// CHECK-NEXT:          "col": 18,
+// CHECK-NEXT:          "tokLen": 1
+// CHECK-NEXT:         }
+// CHECK-NEXT:        },
+// CHECK-NEXT:        "text": " xxx"
+// CHECK-NEXT:       },
+// CHECK-NEXT:       {
+// CHECK-NEXT:        "id": "0x{{.*}}",
+// CHECK-NEXT:        "kind": "TextComment",
+// CHECK-NEXT:        "loc": {
+// CHECK-NEXT:         "offset": 650,
+// CHECK-NEXT:         "line": 39,
+// CHECK-NEXT:         "col": 4,
+// CHECK-NEXT:         "tokLen": 0
+// CHECK-NEXT:        },
+// CHECK-NEXT:        "range": {
+// CHECK-NEXT:         "begin": {
+// CHECK-NEXT:          "offset": 650,
+// CHECK-NEXT:          "col": 4,
+// CHECK-NEXT:          "tokLen": 0
+// CHECK-NEXT:         },
+// CHECK-NEXT:         "end": {
+// CHECK-NEXT:          "offset": 650,
+// CHECK-NEXT:          "col": 4,
+// CHECK-NEXT:          "tokLen": 0
+// CHECK-NEXT:         }
+// CHECK-NEXT:        },
+// CHECK-NEXT:        "text": " "
+// CHECK-NEXT:       }
+// CHECK-NEXT:      ]
+// CHECK-NEXT:     }
+// CHECK-NEXT:    ]
+// CHECK-NEXT:   },
+// CHECK-NEXT:   {
+// CHECK-NEXT:    "id": "0x{{.*}}",
+// CHECK-NEXT:    "kind": "ParamCommandComment",
+// CHECK-NEXT:    "loc": {
+// CHECK-NEXT:     "offset": 652,
+// CHECK-NEXT:     "col": 6,
+// CHECK-NEXT:     "tokLen": 5
+// CHECK-NEXT:    },
+// CHECK-NEXT:    "range": {
+// CHECK-NEXT:     "begin": {
+// CHECK-NEXT:      "offset": 651,
+// CHECK-NEXT:      "col": 5,
+// CHECK-NEXT:      "tokLen": 1
+// CHECK-NEXT:     },
+// CHECK-NEXT:     "end": {
+// CHECK-NEXT:      "offset": 682,
+// CHECK-NEXT:      "line": 40,
+// CHECK-NEXT:      "col": 4,
+// CHECK-NEXT:      "tokLen": 0
+// CHECK-NEXT:     }
+// CHECK-NEXT:    },
+// CHECK-NEXT:    "direction": "in",
+// CHECK-NEXT:    "params": [
+// CHECK-NEXT:     "bbb"
+// CHECK-NEXT:    ],
+// CHECK-NEXT:    "positions": [
+// CHECK-NEXT:     "invalid"
+// CHECK-NEXT:    ],
+// CHECK-NEXT:    "inner": [
+// CHECK-NEXT:     {
+// CHECK-NEXT:      "id": "0x{{.*}}",
+// CHECK-NEXT:      "kind": "ParagraphComment",
+// CHECK-NEXT:      "loc": {
+// CHECK-NEXT:       "offset": 661,
+// CHECK-NEXT:       "line": 39,
+// CHECK-NEXT:       "col": 15,
+// CHECK-NEXT:       "tokLen": 0
+// CHECK-NEXT:      },
+// CHECK-NEXT:      "range": {
+// CHECK-NEXT:       "begin": {
+// CHECK-NEXT:        "offset": 661,
+// CHECK-NEXT:        "col": 15,
+// CHECK-NEXT:        "tokLen": 0
+// CHECK-NEXT:       },
+// CHECK-NEXT:       "end": {
+// CHECK-NEXT:        "offset": 682,
+// CHECK-NEXT:        "line": 40,
+// CHECK-NEXT:        "col": 4,
+// CHECK-NEXT:        "tokLen": 0
+// CHECK-NEXT:       }
+// CHECK-NEXT:      },
+// CHECK-NEXT:      "inner": [
+// CHECK-NEXT:       {
+// CHECK-NEXT:        "id": "0x{{.*}}",
+// CHECK-NEXT:        "kind": "TextComment",
+// CHECK-NEXT:        "loc": {
+// CHECK-NEXT:         "offset": 661,
+// CHECK-NEXT:         "line": 39,
+// CHECK-NEXT:         "col": 15,
+// CHECK-NEXT:         "tokLen": 0
+// CHECK-NEXT:        },
+// CHECK-NEXT:        "range": {
+// CHECK-NEXT:         "begin": {
+// CHECK-NEXT:          "offset": 661,
+// CHECK-NEXT:          "col": 15,
+// CHECK-NEXT:          "tokLen": 0
+// CHECK-NEXT:         },
+// CHECK-NEXT:         "end": {
+// CHECK-NEXT:          "offset": 677,
+// CHECK-NEXT:          "col": 31,
+// CHECK-NEXT:          "tokLen": 1
+// CHECK-NEXT:         }
+// CHECK-NEXT:        },
+// CHECK-NEXT:        "text": " Invalid argument"
+// CHECK-NEXT:       },
+// CHECK-NEXT:       {
+// CHECK-NEXT:        "id": "0x{{.*}}",
+// CHECK-NEXT:        "kind": "TextComment",
+// CHECK-NEXT:        "loc": {
+// CHECK-NEXT:         "offset": 682,
+// CHECK-NEXT:         "line": 40,
+// CHECK-NEXT:         "col": 4,
+// CHECK-NEXT:         "tokLen": 0
+// CHECK-NEXT:        },
+// CHECK-NEXT:        "range": {
+// CHECK-NEXT:         "begin": {
+// CHECK-NEXT:          "offset": 682,
+// CHECK-NEXT:          "col": 4,
+// CHECK-NEXT:          "tokLen": 0
+// CHECK-NEXT:         },
+// CHECK-NEXT:         "end": {
+// CHECK-NEXT:          "offset": 682,
+// CHECK-NEXT:          "col": 4,
+// CHECK-NEXT:          "tokLen": 0
+// CHECK-NEXT:         }
+// CHECK-NEXT:        },
+// CHECK-NEXT:        "text": " "
+// CHECK-NEXT:       }
+// CHECK-NEXT:      ]
+// CHECK-NEXT:     }
+// CHECK-NEXT:    ]
+// CHECK-NEXT:   },
+// CHECK-NEXT:   {
+// CHECK-NEXT:    "id": "0x{{.*}}",
+// CHECK-NEXT:    "kind": "ParamCommandComment",
+// CHECK-NEXT:    "loc": {
+// CHECK-NEXT:     "offset": 684,
+// CHECK-NEXT:     "col": 6,
+// CHECK-NEXT:     "tokLen": 5
+// CHECK-NEXT:    },
+// CHECK-NEXT:    "range": {
+// CHECK-NEXT:     "begin": {
+// CHECK-NEXT:      "offset": 683,
+// CHECK-NEXT:      "col": 5,
+// CHECK-NEXT:      "tokLen": 1
+// CHECK-NEXT:     },
+// CHECK-NEXT:     "end": {
+// CHECK-NEXT:      "offset": 707,
+// CHECK-NEXT:      "col": 29,
+// CHECK-NEXT:      "tokLen": 1
+// CHECK-NEXT:     }
+// CHECK-NEXT:    },
+// CHECK-NEXT:    "direction": "in",
+// CHECK-NEXT:    "params": [
+// CHECK-NEXT:     "..."
+// CHECK-NEXT:    ],
+// CHECK-NEXT:    "positions": [
+// CHECK-NEXT:     "..."
+// CHECK-NEXT:    ],
+// CHECK-NEXT:    "inner": [
+// CHECK-NEXT:     {
+// CHECK-NEXT:      "id": "0x{{.*}}",
+// CHECK-NEXT:      "kind": "ParagraphComment",
+// CHECK-NEXT:      "loc": {
+// CHECK-NEXT:       "offset": 693,
+// CHECK-NEXT:       "col": 15,
+// CHECK-NEXT:       "tokLen": 0
+// CHECK-NEXT:      },
+// CHECK-NEXT:      "range": {
+// CHECK-NEXT:       "begin": {
+// CHECK-NEXT:        "offset": 693,
+// CHECK-NEXT:        "col": 15,
+// CHECK-NEXT:        "tokLen": 0
+// CHECK-NEXT:       },
+// CHECK-NEXT:       "end": {
+// CHECK-NEXT:        "offset": 707,
+// CHECK-NEXT:        "col": 29,
+// CHECK-NEXT:        "tokLen": 1
+// CHECK-NEXT:       }
+// CHECK-NEXT:      },
+// CHECK-NEXT:      "inner": [
+// CHECK-NEXT:       {
+// CHECK-NEXT:        "id": "0x{{.*}}",
+// CHECK-NEXT:        "kind": "TextComment",
+// CHECK-NEXT:        "loc": {
+// CHECK-NEXT:         "offset": 693,
+// CHECK-NEXT:         "col": 15,
+// CHECK-NEXT:         "tokLen": 0
+// CHECK-NEXT:        },
+// CHECK-NEXT:        "range": {
+// CHECK-NEXT:         "begin": {
+// CHECK-NEXT:          "offset": 693,
+// CHECK-NEXT:          "col": 15,
+// CHECK-NEXT:          "tokLen": 0
+// CHECK-NEXT:         },
+// CHECK-NEXT:         "end": {
+// CHECK-NEXT:          "offset": 707,
+// CHECK-NEXT:          "col": 29,
+// CHECK-NEXT:          "tokLen": 1
+// CHECK-NEXT:         }
+// CHECK-NEXT:        },
+// CHECK-NEXT:        "text": " More arguments"
+// CHECK-NEXT:       }
+// CHECK-NEXT:      ]
+// CHECK-NEXT:     }
+// CHECK-NEXT:    ]
+// CHECK-NEXT:   }
+// CHECK-NEXT:  ]
+// CHECK-NEXT: }
+
+
+// CHECK:  "kind": "FullComment",
+// CHECK-NEXT:  "loc": {
+// CHECK-NEXT:   "offset": 793,
+// CHECK-NEXT:   "line": 44,
+// CHECK-NEXT:   "col": 4,
+// CHECK-NEXT:   "tokLen": 0
+// CHECK-NEXT:  },
+// CHECK-NEXT:  "range": {
+// CHECK-NEXT:   "begin": {
+// CHECK-NEXT:    "offset": 793,
+// CHECK-NEXT:    "col": 4,
+// CHECK-NEXT:    "tokLen": 0
+// CHECK-NEXT:   },
+// CHECK-NEXT:   "end": {
+// CHECK-NEXT:    "offset": 815,
+// CHECK-NEXT:    "col": 26,
+// CHECK-NEXT:    "tokLen": 1
+// CHECK-NEXT:   }
+// CHECK-NEXT:  },
+// CHECK-NEXT:  "inner": [
+// CHECK-NEXT:   {
+// CHECK-NEXT:    "id": "0x{{.*}}",
+// CHECK-NEXT:    "kind": "ParagraphComment",
+// CHECK-NEXT:    "loc": {
+// CHECK-NEXT:     "offset": 793,
+// CHECK-NEXT:     "col": 4,
+// CHECK-NEXT:     "tokLen": 0
+// CHECK-NEXT:    },
+// CHECK-NEXT:    "range": {
+// CHECK-NEXT:     "begin": {
+// CHECK-NEXT:      "offset": 793,
+// CHECK-NEXT:      "col": 4,
+// CHECK-NEXT:      "tokLen": 0
+// CHECK-NEXT:     },
+// CHECK-NEXT:     "end": {
+// CHECK-NEXT:      "offset": 793,
+// CHECK-NEXT:      "col": 4,
+// CHECK-NEXT:      "tokLen": 0
+// CHECK-NEXT:     }
+// CHECK-NEXT:    },
+// CHECK-NEXT:    "inner": [
+// CHECK-NEXT:     {
+// CHECK-NEXT:      "id": "0x{{.*}}",
+// CHECK-NEXT:      "kind": "TextComment",
+// CHECK-NEXT:      "loc": {
+// CHECK-NEXT:       "offset": 793,
+// CHECK-NEXT:       "col": 4,
+// CHECK-NEXT:       "tokLen": 0
+// CHECK-NEXT:      },
+// CHECK-NEXT:      "range": {
+// CHECK-NEXT:       "begin": {
+// CHECK-NEXT:        "offset": 793,
+// CHECK-NEXT:        "col": 4,
+// CHECK-NEXT:        "tokLen": 0
+// CHECK-NEXT:       },
+// CHECK-NEXT:       "end": {
+// CHECK-NEXT:        "offset": 793,
+// CHECK-NEXT:        "col": 4,
+// CHECK-NEXT:        "tokLen": 0
+// CHECK-NEXT:       }
+// CHECK-NEXT:      },
+// CHECK-NEXT:      "text": " "
+// CHECK-NEXT:     }
+// CHECK-NEXT:    ]
+// CHECK-NEXT:   },
+// CHECK-NEXT:   {
+// CHECK-NEXT:    "id": "0x{{.*}}",
+// CHECK-NEXT:    "kind": "ParamCommandComment",
+// CHECK-NEXT:    "loc": {
+// CHECK-NEXT:     "offset": 795,
+// CHECK-NEXT:     "col": 6,
+// CHECK-NEXT:     "tokLen": 5
+// CHECK-NEXT:    },
+// CHECK-NEXT:    "range": {
+// CHECK-NEXT:     "begin": {
+// CHECK-NEXT:      "offset": 794,
+// CHECK-NEXT:      "col": 5,
+// CHECK-NEXT:      "tokLen": 1
+// CHECK-NEXT:     },
+// CHECK-NEXT:     "end": {
+// CHECK-NEXT:      "offset": 815,
+// CHECK-NEXT:      "col": 26,
+// CHECK-NEXT:      "tokLen": 1
+// CHECK-NEXT:     }
+// CHECK-NEXT:    },
+// CHECK-NEXT:    "direction": "in",
+// CHECK-NEXT:    "params": [
+// CHECK-NEXT:     "aaa",
+// CHECK-NEXT:     "bbb",
+// CHECK-NEXT:     "..."
+// CHECK-NEXT:    ],
+// CHECK-NEXT:    "positions": [
+// CHECK-NEXT:     0,
+// CHECK-NEXT:     "invalid",
+// CHECK-NEXT:     "..."
+// CHECK-NEXT:    ],
+// CHECK-NEXT:    "inner": [
+// CHECK-NEXT:     {
+// CHECK-NEXT:      "id": "0x{{.*}}",
+// CHECK-NEXT:      "kind": "ParagraphComment",
+// CHECK-NEXT:      "loc": {
+// CHECK-NEXT:       "offset": 812,
+// CHECK-NEXT:       "col": 23,
+// CHECK-NEXT:       "tokLen": 0
+// CHECK-NEXT:      },
+// CHECK-NEXT:      "range": {
+// CHECK-NEXT:       "begin": {
+// CHECK-NEXT:        "offset": 812,
+// CHECK-NEXT:        "col": 23,
+// CHECK-NEXT:        "tokLen": 0
+// CHECK-NEXT:       },
+// CHECK-NEXT:       "end": {
+// CHECK-NEXT:        "offset": 815,
+// CHECK-NEXT:        "col": 26,
+// CHECK-NEXT:        "tokLen": 1
+// CHECK-NEXT:       }
+// CHECK-NEXT:      },
+// CHECK-NEXT:      "inner": [
+// CHECK-NEXT:       {
+// CHECK-NEXT:        "id": "0x{{.*}}",
+// CHECK-NEXT:        "kind": "TextComment",
+// CHECK-NEXT:        "loc": {
+// CHECK-NEXT:         "offset": 812,
+// CHECK-NEXT:         "col": 23,
+// CHECK-NEXT:         "tokLen": 0
+// CHECK-NEXT:        },
+// CHECK-NEXT:        "range": {
+// CHECK-NEXT:         "begin": {
+// CHECK-NEXT:          "offset": 812,
+// CHECK-NEXT:          "col": 23,
+// CHECK-NEXT:          "tokLen": 0
+// CHECK-NEXT:         },
+// CHECK-NEXT:         "end": {
+// CHECK-NEXT:          "offset": 815,
+// CHECK-NEXT:          "col": 26,
+// CHECK-NEXT:          "tokLen": 1
+// CHECK-NEXT:         }
+// CHECK-NEXT:        },
+// CHECK-NEXT:        "text": " xxx"
+// CHECK-NEXT:       }
+// CHECK-NEXT:      ]
+// CHECK-NEXT:     }
+// CHECK-NEXT:    ]
+// CHECK-NEXT:   }
+// CHECK-NEXT:  ]
+// CHECK-NEXT: }
+
+
+// CHECK:  "kind": "FullComment",
+// CHECK-NEXT:  "loc": {
+// CHECK-NEXT:   "offset": 793,
+// CHECK-NEXT:   "col": 4,
+// CHECK-NEXT:   "tokLen": 0
+// CHECK-NEXT:  },
+// CHECK-NEXT:  "range": {
+// CHECK-NEXT:   "begin": {
+// CHECK-NEXT:    "offset": 793,
+// CHECK-NEXT:    "col": 4,
+// CHECK-NEXT:    "tokLen": 0
+// CHECK-NEXT:   },
+// CHECK-NEXT:   "end": {
+// CHECK-NEXT:    "offset": 815,
+// CHECK-NEXT:    "col": 26,
+// CHECK-NEXT:    "tokLen": 1
+// CHECK-NEXT:   }
+// CHECK-NEXT:  },
+// CHECK-NEXT:  "inner": [
+// CHECK-NEXT:   {
+// CHECK-NEXT:    "id": "0x{{.*}}",
+// CHECK-NEXT:    "kind": "ParagraphComment",
+// CHECK-NEXT:    "loc": {
+// CHECK-NEXT:     "offset": 793,
+// CHECK-NEXT:     "col": 4,
+// CHECK-NEXT:     "tokLen": 0
+// CHECK-NEXT:    },
+// CHECK-NEXT:    "range": {
+// CHECK-NEXT:     "begin": {
+// CHECK-NEXT:      "offset": 793,
+// CHECK-NEXT:      "col": 4,
+// CHECK-NEXT:      "tokLen": 0
+// CHECK-NEXT:     },
+// CHECK-NEXT:     "end": {
+// CHECK-NEXT:      "offset": 793,
+// CHECK-NEXT:      "col": 4,
+// CHECK-NEXT:      "tokLen": 0
+// CHECK-NEXT:     }
+// CHECK-NEXT:    },
+// CHECK-NEXT:    "inner": [
+// CHECK-NEXT:     {
+// CHECK-NEXT:      "id": "0x{{.*}}",
+// CHECK-NEXT:      "kind": "TextComment",
+// CHECK-NEXT:      "loc": {
+// CHECK-NEXT:       "offset": 793,
+// CHECK-NEXT:       "col": 4,
+// CHECK-NEXT:       "tokLen": 0
+// CHECK-NEXT:      },
+// CHECK-NEXT:      "range": {
+// CHECK-NEXT:       "begin": {
+// CHECK-NEXT:        "offset": 793,
+// CHECK-NEXT:        "col": 4,
+// CHECK-NEXT:        "tokLen": 0
+// CHECK-NEXT:       },
+// CHECK-NEXT:       "end": {
+// CHECK-NEXT:        "offset": 793,
+// CHECK-NEXT:        "col": 4,
+// CHECK-NEXT:        "tokLen": 0
+// CHECK-NEXT:       }
+// CHECK-NEXT:      },
+// CHECK-NEXT:      "text": " "
+// CHECK-NEXT:     }
+// CHECK-NEXT:    ]
+// CHECK-NEXT:   },
+// CHECK-NEXT:   {
+// CHECK-NEXT:    "id": "0x{{.*}}",
+// CHECK-NEXT:    "kind": "ParamCommandComment",
+// CHECK-NEXT:    "loc": {
+// CHECK-NEXT:     "offset": 795,
+// CHECK-NEXT:     "col": 6,
+// CHECK-NEXT:     "tokLen": 5
+// CHECK-NEXT:    },
+// CHECK-NEXT:    "range": {
+// CHECK-NEXT:     "begin": {
+// CHECK-NEXT:      "offset": 794,
+// CHECK-NEXT:      "col": 5,
+// CHECK-NEXT:      "tokLen": 1
+// CHECK-NEXT:     },
+// CHECK-NEXT:     "end": {
+// CHECK-NEXT:      "offset": 815,
+// CHECK-NEXT:      "col": 26,
+// CHECK-NEXT:      "tokLen": 1
+// CHECK-NEXT:     }
+// CHECK-NEXT:    },
+// CHECK-NEXT:    "direction": "in",
+// CHECK-NEXT:    "params": [
+// CHECK-NEXT:     "aaa",
+// CHECK-NEXT:     "bbb",
+// CHECK-NEXT:     "..."
+// CHECK-NEXT:    ],
+// CHECK-NEXT:    "positions": [
+// CHECK-NEXT:     0,
+// CHECK-NEXT:     "invalid",
+// CHECK-NEXT:     "..."
+// CHECK-NEXT:    ],
+// CHECK-NEXT:    "inner": [
+// CHECK-NEXT:     {
+// CHECK-NEXT:      "id": "0x{{.*}}",
+// CHECK-NEXT:      "kind": "ParagraphComment",
+// CHECK-NEXT:      "loc": {
+// CHECK-NEXT:       "offset": 812,
+// CHECK-NEXT:       "col": 23,
+// CHECK-NEXT:       "tokLen": 0
+// CHECK-NEXT:      },
+// CHECK-NEXT:      "range": {
+// CHECK-NEXT:       "begin": {
+// CHECK-NEXT:        "offset": 812,
+// CHECK-NEXT:        "col": 23,
+// CHECK-NEXT:        "tokLen": 0
+// CHECK-NEXT:       },
+// CHECK-NEXT:       "end": {
+// CHECK-NEXT:        "offset": 815,
+// CHECK-NEXT:        "col": 26,
+// CHECK-NEXT:        "tokLen": 1
+// CHECK-NEXT:       }
+// CHECK-NEXT:      },
+// CHECK-NEXT:      "inner": [
+// CHECK-NEXT:       {
+// CHECK-NEXT:        "id": "0x{{.*}}",
+// CHECK-NEXT:        "kind": "TextComment",
+// CHECK-NEXT:        "loc": {
+// CHECK-NEXT:         "offset": 812,
+// CHECK-NEXT:         "col": 23,
+// CHECK-NEXT:         "tokLen": 0
+// CHECK-NEXT:        },
+// CHECK-NEXT:        "range": {
+// CHECK-NEXT:         "begin": {
+// CHECK-NEXT:          "offset": 812,
+// CHECK-NEXT:          "col": 23,
+// CHECK-NEXT:          "tokLen": 0
+// CHECK-NEXT:         },
+// CHECK-NEXT:         "end": {
+// CHECK-NEXT:          "offset": 815,
+// CHECK-NEXT:          "col": 26,
+// CHECK-NEXT:          "tokLen": 1
+// CHECK-NEXT:         }
+// CHECK-NEXT:        },
+// CHECK-NEXT:        "text": " xxx"
+// CHECK-NEXT:       }
+// CHECK-NEXT:      ]
+// CHECK-NEXT:     }
+// CHECK-NEXT:    ]
+// CHECK-NEXT:   }
+// CHECK-NEXT:  ]
+// CHECK-NEXT: }

clang/test/AST/ast-dump-comment.cpp

 // CHECK:        BlockCommandComment{{.*}} Name="brief"
 // CHECK-NEXT:     ParagraphComment
 // CHECK-NEXT:       TextComment{{.*}} Text=" Aaa"
 
 /// \param Aaa xxx
 /// \param [in,out] Bbb yyy
 void Test_ParamCommandComment(int Aaa, int Bbb);
 // CHECK:      FunctionDecl{{.*}}Test_ParamCommandComment
-// CHECK:        ParamCommandComment{{.*}} [in] implicitly Param="Aaa" ParamIndex=0
+// CHECK:        ParamCommandComment{{.*}} [in] implicitly Param=[Aaa] ParamIndex=[0]
 // CHECK-NEXT:     ParagraphComment
 // CHECK-NEXT:       TextComment{{.*}} Text=" xxx"
-// CHECK:        ParamCommandComment{{.*}} [in,out] explicitly Param="Bbb" ParamIndex=1
+// CHECK:        ParamCommandComment{{.*}} [in,out] explicitly Param=[Bbb] ParamIndex=[1]
 // CHECK-NEXT:     ParagraphComment
 // CHECK-NEXT:       TextComment{{.*}} Text=" yyy"
 
 /// \tparam Aaa xxx
 template <typename Aaa> class Test_TParamCommandComment;
 // CHECK:      ClassTemplateDecl{{.*}}Test_TParamCommandComment
 // CHECK:        TParamCommandComment{{.*}} Param="Aaa" Position=<0>
 // CHECK-NEXT:     ParagraphComment

 /// Aaa
 /// \endverbatim
 int Test_VerbatimBlockComment;
 // CHECK:      VarDecl{{.*}}Test_VerbatimBlockComment
 // CHECK:        VerbatimBlockComment{{.*}} Name="verbatim" CloseName="endverbatim"
 // CHECK-NEXT:     VerbatimBlockLineComment{{.*}} Text=" Aaa"
 
 /// \param ... More arguments
 template<typename T>
-void Test_TemplatedFunctionVariadic(int arg, ...);
+void Test_TemplatedFunctionVariadic(...);
 // CHECK:      FunctionTemplateDecl{{.*}}Test_TemplatedFunctionVariadic
-// CHECK:        ParamCommandComment{{.*}} [in] implicitly Param="..."
+// CHECK:        ParamCommandComment{{.*}} [in] implicitly Param=[...] ParamIndex=[...]
 // CHECK-NEXT:     ParagraphComment
 // CHECK-NEXT:       TextComment{{.*}} Text=" More arguments"
+
+/// \param aaa xxx
+/// \param bbb Invalid argument
+/// \param ... More arguments
+template<typename T>
+void Test_TemplatedFunctionParamAndVariadic(int aaa, ...);
+// CHECK:      FunctionTemplateDecl{{.*}}Test_TemplatedFunctionParamAndVariadic
+// CHECK:        ParamCommandComment{{.*}} [in] implicitly Param=[aaa] ParamIndex=[0]
+// CHECK-NEXT:     ParagraphComment
+// CHECK-NEXT:       TextComment{{.*}} Text=" xxx"
+// CHECK:        ParamCommandComment{{.*}} [in] implicitly Param=[bbb] ParamIndex=[invalid]
+// CHECK-NEXT:     ParagraphComment
+// CHECK-NEXT:       TextComment{{.*}} Text=" Invalid argument"
+// CHECK:        ParamCommandComment{{.*}} [in] implicitly Param=[...] ParamIndex=[...]
+// CHECK-NEXT:     ParagraphComment
+// CHECK-NEXT:       TextComment{{.*}} Text=" More arguments"
+
+/// \param aaa,bbb,... xxx
+template<typename T>
+void Test_TemplatedFunctionParamAndVariadic2(int aaa, ...);
+// CHECK:      FunctionTemplateDecl{{.*}}Test_TemplatedFunctionParamAndVariadic
+// CHECK:        ParamCommandComment{{.*}} [in] implicitly Param=[aaa, bbb, ...] ParamIndex=[0, invalid, ...]
+// CHECK-NEXT:     ParagraphComment
+// CHECK-NEXT:       TextComment{{.*}} Text=" xxx"

clang/test/Index/comment-to-html-xml-conversion.cpp

 
 //===---
 // Tests for \param.
 //===---
 
 /// \param
 void test_cmd_param_1(int x1);
 
 // CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:6: FunctionDecl=test_cmd_param_1:{{.*}} FullCommentAsHTML=[] FullCommentAsXML=[<Function file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="6"><Name>test_cmd_param_1</Name><USR>c:@F@test_cmd_param_1#I#</USR><Declaration>void test_cmd_param_1(int x1)</Declaration></Function>]
 // CHECK-NEXT:  CommentAST=[
 // CHECK-NEXT:    (CXComment_FullComment
 // CHECK-NEXT:       (CXComment_Paragraph IsWhitespace
 // CHECK-NEXT:         (CXComment_Text Text=[ ] IsWhitespace))
-// CHECK-NEXT:       (CXComment_ParamCommand in implicitly ParamName=[] ParamIndex=Invalid
+// CHECK-NEXT:       (CXComment_ParamCommand in implicitly
 // CHECK-NEXT:         (CXComment_Paragraph IsWhitespace)))]
 
 /// \param x1 Aaa.
 void test_cmd_param_2(int x1);
 
-// CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:6: FunctionDecl=test_cmd_param_2:{{.*}} FullCommentAsHTML=[<dl><dt class="param-name-index-0">x1</dt><dd class="param-descr-index-0"> Aaa.</dd></dl>] FullCommentAsXML=[<Function file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="6"><Name>test_cmd_param_2</Name><USR>c:@F@test_cmd_param_2#I#</USR><Declaration>void test_cmd_param_2(int x1)</Declaration><Parameters><Parameter><Name>x1</Name><Index>0</Index><Direction isExplicit="0">in</Direction><Discussion><Para> Aaa.</Para></Discussion></Parameter></Parameters></Function>]
+// CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:6: FunctionDecl=test_cmd_param_2:{{.*}} FullCommentAsHTML=[<dl><dt class="param-name-index-0">x1</dt><dd class="param-descr-index-0"> Aaa.</dd></dl>] FullCommentAsXML=[<Function file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="6"><Name>test_cmd_param_2</Name><USR>c:@F@test_cmd_param_2#I#</USR><Declaration>void test_cmd_param_2(int x1)</Declaration><Parameters><Parameter><Identifiers><Identifier><Name>x1</Name><Index>0</Index></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> Aaa.</Para></Discussion></Parameter></Parameters></Function>]
 // CHECK-NEXT:  CommentAST=[
 // CHECK-NEXT:    (CXComment_FullComment
 // CHECK-NEXT:       (CXComment_Paragraph IsWhitespace
 // CHECK-NEXT:         (CXComment_Text Text=[ ] IsWhitespace))
-// CHECK-NEXT:       (CXComment_ParamCommand in implicitly ParamName=[x1] ParamIndex=0
+// CHECK-NEXT:       (CXComment_ParamCommand in implicitly ParamName[0]=[x1] ParamIndex[0]=0
 // CHECK-NEXT:         (CXComment_Paragraph
 // CHECK-NEXT:           (CXComment_Text Text=[ Aaa.]))))]
 
 /// \param zzz Aaa.
 void test_cmd_param_3(int x1);
 
-// CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:6: FunctionDecl=test_cmd_param_3:{{.*}} FullCommentAsHTML=[<dl><dt class="param-name-index-invalid">zzz</dt><dd class="param-descr-index-invalid"> Aaa.</dd></dl>] FullCommentAsXML=[<Function file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="6"><Name>test_cmd_param_3</Name><USR>c:@F@test_cmd_param_3#I#</USR><Declaration>void test_cmd_param_3(int x1)</Declaration><Parameters><Parameter><Name>zzz</Name><Direction isExplicit="0">in</Direction><Discussion><Para> Aaa.</Para></Discussion></Parameter></Parameters></Function>]
+// CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:6: FunctionDecl=test_cmd_param_3:{{.*}} FullCommentAsHTML=[<dl><dt class="param-name-index-invalid">zzz</dt><dd class="param-descr-index-invalid"> Aaa.</dd></dl>] FullCommentAsXML=[<Function file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="6"><Name>test_cmd_param_3</Name><USR>c:@F@test_cmd_param_3#I#</USR><Declaration>void test_cmd_param_3(int x1)</Declaration><Parameters><Parameter><Identifiers><Identifier><Name>zzz</Name></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> Aaa.</Para></Discussion></Parameter></Parameters></Function>]
 // CHECK-NEXT:  CommentAST=[
 // CHECK-NEXT:    (CXComment_FullComment
 // CHECK-NEXT:       (CXComment_Paragraph IsWhitespace
 // CHECK-NEXT:         (CXComment_Text Text=[ ] IsWhitespace))
-// CHECK-NEXT:       (CXComment_ParamCommand in implicitly ParamName=[zzz] ParamIndex=Invalid
+// CHECK-NEXT:       (CXComment_ParamCommand in implicitly ParamName[0]=[zzz] ParamIndex[0]=Invalid
 // CHECK-NEXT:         (CXComment_Paragraph
 // CHECK-NEXT:           (CXComment_Text Text=[ Aaa.]))))]
 
 /// \param x2 Bbb.
 /// \param x1 Aaa.
 void test_cmd_param_4(int x1, int x2);
 
-// CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:6: FunctionDecl=test_cmd_param_4:{{.*}} FullCommentAsHTML=[<dl><dt class="param-name-index-0">x1</dt><dd class="param-descr-index-0"> Aaa.</dd><dt class="param-name-index-1">x2</dt><dd class="param-descr-index-1"> Bbb. </dd></dl>] FullCommentAsXML=[<Function file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="6"><Name>test_cmd_param_4</Name><USR>c:@F@test_cmd_param_4#I#I#</USR><Declaration>void test_cmd_param_4(int x1, int x2)</Declaration><Parameters><Parameter><Name>x1</Name><Index>0</Index><Direction isExplicit="0">in</Direction><Discussion><Para> Aaa.</Para></Discussion></Parameter><Parameter><Name>x2</Name><Index>1</Index><Direction isExplicit="0">in</Direction><Discussion><Para> Bbb. </Para></Discussion></Parameter></Parameters></Function>]
+// CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:6: FunctionDecl=test_cmd_param_4:{{.*}} FullCommentAsHTML=[<dl><dt class="param-name-index-0">x1</dt><dd class="param-descr-index-0"> Aaa.</dd><dt class="param-name-index-1">x2</dt><dd class="param-descr-index-1"> Bbb. </dd></dl>] FullCommentAsXML=[<Function file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="6"><Name>test_cmd_param_4</Name><USR>c:@F@test_cmd_param_4#I#I#</USR><Declaration>void test_cmd_param_4(int x1, int x2)</Declaration><Parameters><Parameter><Identifiers><Identifier><Name>x1</Name><Index>0</Index></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> Aaa.</Para></Discussion></Parameter><Parameter><Identifiers><Identifier><Name>x2</Name><Index>1</Index></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> Bbb. </Para></Discussion></Parameter></Parameters></Function>]
 // CHECK-NEXT:  CommentAST=[
 // CHECK-NEXT:    (CXComment_FullComment
 // CHECK-NEXT:       (CXComment_Paragraph IsWhitespace
 // CHECK-NEXT:         (CXComment_Text Text=[ ] IsWhitespace))
-// CHECK-NEXT:       (CXComment_ParamCommand in implicitly ParamName=[x2] ParamIndex=1
+// CHECK-NEXT:       (CXComment_ParamCommand in implicitly ParamName[0]=[x2] ParamIndex[0]=1
 // CHECK-NEXT:         (CXComment_Paragraph
 // CHECK-NEXT:           (CXComment_Text Text=[ Bbb.] HasTrailingNewline)
 // CHECK-NEXT:           (CXComment_Text Text=[ ] IsWhitespace)))
-// CHECK-NEXT:       (CXComment_ParamCommand in implicitly ParamName=[x1] ParamIndex=0
+// CHECK-NEXT:       (CXComment_ParamCommand in implicitly ParamName[0]=[x1] ParamIndex[0]=0
 // CHECK-NEXT:         (CXComment_Paragraph
 // CHECK-NEXT:           (CXComment_Text Text=[ Aaa.]))))]
 
 /// \param x2 Bbb.
 /// \param zzz Aaa.
 /// \param x1 Aaa.
 void test_cmd_param_5(int x1, int x2);
 
-// CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:6: FunctionDecl=test_cmd_param_5:{{.*}} FullCommentAsHTML=[<dl><dt class="param-name-index-0">x1</dt><dd class="param-descr-index-0"> Aaa.</dd><dt class="param-name-index-1">x2</dt><dd class="param-descr-index-1"> Bbb. </dd><dt class="param-name-index-invalid">zzz</dt><dd class="param-descr-index-invalid"> Aaa. </dd></dl>] FullCommentAsXML=[<Function file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="6"><Name>test_cmd_param_5</Name><USR>c:@F@test_cmd_param_5#I#I#</USR><Declaration>void test_cmd_param_5(int x1, int x2)</Declaration><Parameters><Parameter><Name>x1</Name><Index>0</Index><Direction isExplicit="0">in</Direction><Discussion><Para> Aaa.</Para></Discussion></Parameter><Parameter><Name>x2</Name><Index>1</Index><Direction isExplicit="0">in</Direction><Discussion><Para> Bbb. </Para></Discussion></Parameter><Parameter><Name>zzz</Name><Direction isExplicit="0">in</Direction><Discussion><Para> Aaa. </Para></Discussion></Parameter></Parameters></Function>]
+// CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:6: FunctionDecl=test_cmd_param_5:{{.*}} FullCommentAsHTML=[<dl><dt class="param-name-index-0">x1</dt><dd class="param-descr-index-0"> Aaa.</dd><dt class="param-name-index-1">x2</dt><dd class="param-descr-index-1"> Bbb. </dd><dt class="param-name-index-invalid">zzz</dt><dd class="param-descr-index-invalid"> Aaa. </dd></dl>] FullCommentAsXML=[<Function file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="6"><Name>test_cmd_param_5</Name><USR>c:@F@test_cmd_param_5#I#I#</USR><Declaration>void test_cmd_param_5(int x1, int x2)</Declaration><Parameters><Parameter><Identifiers><Identifier><Name>x1</Name><Index>0</Index></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> Aaa.</Para></Discussion></Parameter><Parameter><Identifiers><Identifier><Name>x2</Name><Index>1</Index></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> Bbb. </Para></Discussion></Parameter><Parameter><Identifiers><Identifier><Name>zzz</Name></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> Aaa. </Para></Discussion></Parameter></Parameters></Function>]
 // CHECK-NEXT:  CommentAST=[
 // CHECK-NEXT:    (CXComment_FullComment
 // CHECK-NEXT:       (CXComment_Paragraph IsWhitespace
 // CHECK-NEXT:         (CXComment_Text Text=[ ] IsWhitespace))
-// CHECK-NEXT:       (CXComment_ParamCommand in implicitly ParamName=[x2] ParamIndex=1
+// CHECK-NEXT:       (CXComment_ParamCommand in implicitly ParamName[0]=[x2] ParamIndex[0]=1
 // CHECK-NEXT:         (CXComment_Paragraph
 // CHECK-NEXT:           (CXComment_Text Text=[ Bbb.] HasTrailingNewline)
 // CHECK-NEXT:           (CXComment_Text Text=[ ] IsWhitespace)))
-// CHECK-NEXT:       (CXComment_ParamCommand in implicitly ParamName=[zzz] ParamIndex=Invalid
+// CHECK-NEXT:       (CXComment_ParamCommand in implicitly ParamName[0]=[zzz] ParamIndex[0]=Invalid
 // CHECK-NEXT:         (CXComment_Paragraph
 // CHECK-NEXT:           (CXComment_Text Text=[ Aaa.] HasTrailingNewline)
 // CHECK-NEXT:           (CXComment_Text Text=[ ] IsWhitespace)))
-// CHECK-NEXT:       (CXComment_ParamCommand in implicitly ParamName=[x1] ParamIndex=0
+// CHECK-NEXT:       (CXComment_ParamCommand in implicitly ParamName[0]=[x1] ParamIndex[0]=0
 // CHECK-NEXT:         (CXComment_Paragraph
 // CHECK-NEXT:           (CXComment_Text Text=[ Aaa.]))))]
 
 /// \param x1 Aaa.
 /// \param ... Bbb.
 void test_cmd_param_6(int x1, ...);
 
-// CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:6: FunctionDecl=test_cmd_param_6:{{.*}} FullCommentAsHTML=[<dl><dt class="param-name-index-0">x1</dt><dd class="param-descr-index-0"> Aaa. </dd><dt class="param-name-index-vararg">...</dt><dd class="param-descr-index-vararg"> Bbb.</dd></dl>] FullCommentAsXML=[<Function file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="6"><Name>test_cmd_param_6</Name><USR>c:@F@test_cmd_param_6#I.#</USR><Declaration>void test_cmd_param_6(int x1, ...)</Declaration><Parameters><Parameter><Name>x1</Name><Index>0</Index><Direction isExplicit="0">in</Direction><Discussion><Para> Aaa. </Para></Discussion></Parameter><Parameter><Name>...</Name><IsVarArg /><Direction isExplicit="0">in</Direction><Discussion><Para> Bbb.</Para></Discussion></Parameter></Parameters></Function>]
+// CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:6: FunctionDecl=test_cmd_param_6:{{.*}} FullCommentAsHTML=[<dl><dt class="param-name-index-0">x1</dt><dd class="param-descr-index-0"> Aaa. </dd><dt class="param-name-index-vararg">...</dt><dd class="param-descr-index-vararg"> Bbb.</dd></dl>] FullCommentAsXML=[<Function file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="6"><Name>test_cmd_param_6</Name><USR>c:@F@test_cmd_param_6#I.#</USR><Declaration>void test_cmd_param_6(int x1, ...)</Declaration><Parameters><Parameter><Identifiers><Identifier><Name>x1</Name><Index>0</Index></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> Aaa. </Para></Discussion></Parameter><Parameter><Identifiers><Identifier><Name>...</Name><IsVarArg /></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> Bbb.</Para></Discussion></Parameter></Parameters></Function>]
 // CHECK-NEXT:  CommentAST=[
 // CHECK-NEXT:    (CXComment_FullComment
 // CHECK-NEXT:       (CXComment_Paragraph IsWhitespace
 // CHECK-NEXT:         (CXComment_Text Text=[ ] IsWhitespace))
-// CHECK-NEXT:       (CXComment_ParamCommand in implicitly ParamName=[x1] ParamIndex=0
+// CHECK-NEXT:       (CXComment_ParamCommand in implicitly ParamName[0]=[x1] ParamIndex[0]=0
 // CHECK-NEXT:         (CXComment_Paragraph
 // CHECK-NEXT:           (CXComment_Text Text=[ Aaa.] HasTrailingNewline)
 // CHECK-NEXT:           (CXComment_Text Text=[ ] IsWhitespace)))
-// CHECK-NEXT:       (CXComment_ParamCommand in implicitly ParamName=[...] ParamIndex=4294967295
+// CHECK-NEXT:       (CXComment_ParamCommand in implicitly ParamName[0]=[...] ParamIndex[0]=Variadic
 // CHECK-NEXT:         (CXComment_Paragraph
 // CHECK-NEXT:           (CXComment_Text Text=[ Bbb.]))))]
 
 //===---
 // Tests for \tparam.
 //===---
 
 /// \tparam
 /// \param aaa Blah blah
 template<typename T>
 void test_cmd_tparam_1(T aaa);
 
-// CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:6: FunctionTemplate=test_cmd_tparam_1:{{.*}} FullCommentAsHTML=[<dl><dt class="param-name-index-0">aaa</dt><dd class="param-descr-index-0"> Blah blah</dd></dl>] FullCommentAsXML=[<Function templateKind="template" file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="6"><Name>test_cmd_tparam_1</Name><USR>c:@FT@&gt;1#Ttest_cmd_tparam_1#t0.0#v#</USR><Declaration>template &lt;typename T&gt; void test_cmd_tparam_1(T aaa)</Declaration><Parameters><Parameter><Name>aaa</Name><Index>0</Index><Direction isExplicit="0">in</Direction><Discussion><Para> Blah blah</Para></Discussion></Parameter></Parameters></Function>]
+// CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:6: FunctionTemplate=test_cmd_tparam_1:{{.*}} FullCommentAsHTML=[<dl><dt class="param-name-index-0">aaa</dt><dd class="param-descr-index-0"> Blah blah</dd></dl>] FullCommentAsXML=[<Function templateKind="template" file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="6"><Name>test_cmd_tparam_1</Name><USR>c:@FT@&gt;1#Ttest_cmd_tparam_1#t0.0#v#</USR><Declaration>template &lt;typename T&gt; void test_cmd_tparam_1(T aaa)</Declaration><Parameters><Parameter><Identifiers><Identifier><Name>aaa</Name><Index>0</Index></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> Blah blah</Para></Discussion></Parameter></Parameters></Function>]
 // CHECK-NEXT:  CommentAST=[
 // CHECK-NEXT:    (CXComment_FullComment
 // CHECK-NEXT:       (CXComment_Paragraph IsWhitespace
 // CHECK-NEXT:         (CXComment_Text Text=[ ] IsWhitespace))
 // CHECK-NEXT:       (CXComment_TParamCommand ParamName=[] ParamPosition=Invalid
 // CHECK-NEXT:         (CXComment_Paragraph IsWhitespace
 // CHECK-NEXT:           (CXComment_Text Text=[ ] IsWhitespace)))
-// CHECK-NEXT:       (CXComment_ParamCommand in implicitly ParamName=[aaa] ParamIndex=0
+// CHECK-NEXT:       (CXComment_ParamCommand in implicitly ParamName[0]=[aaa] ParamIndex[0]=0
 // CHECK-NEXT:         (CXComment_Paragraph
 // CHECK-NEXT:           (CXComment_Text Text=[ Blah blah]))))]
 
 /// \tparam T
 /// \param aaa Blah blah
 template<typename T>
 void test_cmd_tparam_2(T aaa);
 
-// CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:6: FunctionTemplate=test_cmd_tparam_2:{{.*}} FullCommentAsHTML=[<dl><dt class="param-name-index-0">aaa</dt><dd class="param-descr-index-0"> Blah blah</dd></dl>] FullCommentAsXML=[<Function templateKind="template" file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="6"><Name>test_cmd_tparam_2</Name><USR>c:@FT@&gt;1#Ttest_cmd_tparam_2#t0.0#v#</USR><Declaration>template &lt;typename T&gt; void test_cmd_tparam_2(T aaa)</Declaration><Parameters><Parameter><Name>aaa</Name><Index>0</Index><Direction isExplicit="0">in</Direction><Discussion><Para> Blah blah</Para></Discussion></Parameter></Parameters></Function>]
+// CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:6: FunctionTemplate=test_cmd_tparam_2:{{.*}} FullCommentAsHTML=[<dl><dt class="param-name-index-0">aaa</dt><dd class="param-descr-index-0"> Blah blah</dd></dl>] FullCommentAsXML=[<Function templateKind="template" file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="6"><Name>test_cmd_tparam_2</Name><USR>c:@FT@&gt;1#Ttest_cmd_tparam_2#t0.0#v#</USR><Declaration>template &lt;typename T&gt; void test_cmd_tparam_2(T aaa)</Declaration><Parameters><Parameter><Identifiers><Identifier><Name>aaa</Name><Index>0</Index></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> Blah blah</Para></Discussion></Parameter></Parameters></Function>]
 // CHECK-NEXT:  CommentAST=[
 // CHECK-NEXT:    (CXComment_FullComment
 // CHECK-NEXT:       (CXComment_Paragraph IsWhitespace
 // CHECK-NEXT:         (CXComment_Text Text=[ ] IsWhitespace))
 // CHECK-NEXT:       (CXComment_TParamCommand ParamName=[T] ParamPosition={0}
 // CHECK-NEXT:         (CXComment_Paragraph IsWhitespace
 // CHECK-NEXT:           (CXComment_Text Text=[ ] IsWhitespace)))
-// CHECK-NEXT:       (CXComment_ParamCommand in implicitly ParamName=[aaa] ParamIndex=0
+// CHECK-NEXT:       (CXComment_ParamCommand in implicitly ParamName[0]=[aaa] ParamIndex[0]=0
 // CHECK-NEXT:         (CXComment_Paragraph
 // CHECK-NEXT:           (CXComment_Text Text=[ Blah blah]))))]
 
 /// \tparam T2 Bbb
 /// \tparam T1 Aaa
 template<typename T1, typename T2>
 void test_cmd_tparam_3(T1 aaa, T2 bbb);
 

 ///
 /// Bbb.
 ///
 /// \param x2 Ddd.
 /// \param x1 Ccc.
 /// \returns Eee.
 void test_full_comment_1(int x1, int x2);
 
-// CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:6: FunctionDecl=test_full_comment_1:{{.*}} FullCommentAsHTML=[<p class="para-brief"> Aaa.</p><p> Bbb.</p><dl><dt class="param-name-index-0">x1</dt><dd class="param-descr-index-0"> Ccc. </dd><dt class="param-name-index-1">x2</dt><dd class="param-descr-index-1"> Ddd. </dd></dl><div class="result-discussion"><p class="para-returns"><span class="word-returns">Returns</span>  Eee.</p></div>] FullCommentAsXML=[<Function file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="6"><Name>test_full_comment_1</Name><USR>c:@F@test_full_comment_1#I#I#</USR><Declaration>void test_full_comment_1(int x1, int x2)</Declaration><Abstract><Para> Aaa.</Para></Abstract><Parameters><Parameter><Name>x1</Name><Index>0</Index><Direction isExplicit="0">in</Direction><Discussion><Para> Ccc. </Para></Discussion></Parameter><Parameter><Name>x2</Name><Index>1</Index><Direction isExplicit="0">in</Direction><Discussion><Para> Ddd. </Para></Discussion></Parameter></Parameters><ResultDiscussion><Para> Eee.</Para></ResultDiscussion><Discussion><Para> Bbb.</Para></Discussion></Function>]
+// CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:6: FunctionDecl=test_full_comment_1:{{.*}} FullCommentAsHTML=[<p class="para-brief"> Aaa.</p><p> Bbb.</p><dl><dt class="param-name-index-0">x1</dt><dd class="param-descr-index-0"> Ccc. </dd><dt class="param-name-index-1">x2</dt><dd class="param-descr-index-1"> Ddd. </dd></dl><div class="result-discussion"><p class="para-returns"><span class="word-returns">Returns</span>  Eee.</p></div>] FullCommentAsXML=[<Function file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="6"><Name>test_full_comment_1</Name><USR>c:@F@test_full_comment_1#I#I#</USR><Declaration>void test_full_comment_1(int x1, int x2)</Declaration><Abstract><Para> Aaa.</Para></Abstract><Parameters><Parameter><Identifiers><Identifier><Name>x1</Name><Index>0</Index></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> Ccc. </Para></Discussion></Parameter><Parameter><Identifiers><Identifier><Name>x2</Name><Index>1</Index></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> Ddd. </Para></Discussion></Parameter></Parameters><ResultDiscussion><Para> Eee.</Para></ResultDiscussion><Discussion><Para> Bbb.</Para></Discussion></Function>]
 // CHECK-NEXT:  CommentAST=[
 // CHECK-NEXT:    (CXComment_FullComment
 // CHECK-NEXT:       (CXComment_Paragraph IsWhitespace
 // CHECK-NEXT:         (CXComment_Text Text=[ ] IsWhitespace))
 // CHECK-NEXT:       (CXComment_BlockCommand CommandName=[brief]
 // CHECK-NEXT:         (CXComment_Paragraph
 // CHECK-NEXT:           (CXComment_Text Text=[ Aaa.])))
 // CHECK-NEXT:       (CXComment_Paragraph
 // CHECK-NEXT:         (CXComment_Text Text=[ Bbb.]))
 // CHECK-NEXT:       (CXComment_Paragraph IsWhitespace
 // CHECK-NEXT:         (CXComment_Text Text=[ ] IsWhitespace))
-// CHECK-NEXT:       (CXComment_ParamCommand in implicitly ParamName=[x2] ParamIndex=1
+// CHECK-NEXT:       (CXComment_ParamCommand in implicitly ParamName[0]=[x2] ParamIndex[0]=1
 // CHECK-NEXT:         (CXComment_Paragraph
 // CHECK-NEXT:           (CXComment_Text Text=[ Ddd.] HasTrailingNewline)
 // CHECK-NEXT:           (CXComment_Text Text=[ ] IsWhitespace)))
-// CHECK-NEXT:       (CXComment_ParamCommand in implicitly ParamName=[x1] ParamIndex=0
+// CHECK-NEXT:       (CXComment_ParamCommand in implicitly ParamName[0]=[x1] ParamIndex[0]=0
 // CHECK-NEXT:         (CXComment_Paragraph
 // CHECK-NEXT:           (CXComment_Text Text=[ Ccc.] HasTrailingNewline)
 // CHECK-NEXT:           (CXComment_Text Text=[ ] IsWhitespace)))
 // CHECK-NEXT:       (CXComment_BlockCommand CommandName=[returns]
 // CHECK-NEXT:         (CXComment_Paragraph
 // CHECK-NEXT:           (CXComment_Text Text=[ Eee.]))))]
 
 //===---

 // CHECK-NEXT:       (CXComment_Paragraph
 // CHECK-NEXT:         (CXComment_Text Text=[ ] IsWhitespace)
 // CHECK-NEXT:         (CXComment_InlineCommand CommandName=[a] RenderEmphasized Arg[0]=Aaa)
 // CHECK-NEXT:         (CXComment_Text Text=[ ] IsWhitespace)
 // CHECK-NEXT:         (CXComment_InlineCommand CommandName=[e] RenderEmphasized Arg[0]=Bbb)
 // CHECK-NEXT:         (CXComment_Text Text=[ ] IsWhitespace)
 // CHECK-NEXT:         (CXComment_InlineCommand CommandName=[em] RenderEmphasized Arg[0]=Ccc)))]
 
-/// \a 1<2 \e 3<4 \em 5<6 \param 7<8 aaa \tparam 9<10 bbb
+/// \a 1<2 \e 3<4 \em 5<6 \param a<8 aaa \tparam 9<10 bbb
 void comment_to_html_conversion_31();
 
-// CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:6: FunctionDecl=comment_to_html_conversion_31:{{.*}} FullCommentAsHTML=[<p class="para-brief"> <em>1&lt;2</em> <em>3&lt;4</em> <em>5&lt;6</em> </p><dl><dt class="tparam-name-index-invalid">9&lt;10</dt><dd class="tparam-descr-index-invalid"> bbb</dd></dl><dl><dt class="param-name-index-invalid">7&lt;8</dt><dd class="param-descr-index-invalid"> aaa </dd></dl>] FullCommentAsXML=[<Function file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="6"><Name>comment_to_html_conversion_31</Name><USR>c:@F@comment_to_html_conversion_31#</USR><Declaration>void comment_to_html_conversion_31()</Declaration><Abstract><Para> <emphasized>1&lt;2</emphasized> <emphasized>3&lt;4</emphasized> <emphasized>5&lt;6</emphasized> </Para></Abstract><TemplateParameters><Parameter><Name>9&lt;10</Name><Discussion><Para> bbb</Para></Discussion></Parameter></TemplateParameters><Parameters><Parameter><Name>7&lt;8</Name><Direction isExplicit="0">in</Direction><Discussion><Para> aaa </Para></Discussion></Parameter></Parameters></Function>]
+// CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:6: FunctionDecl=comment_to_html_conversion_31:{{.*}} FullCommentAsHTML=[<p class="para-brief"> <em>1&lt;2</em> <em>3&lt;4</em> <em>5&lt;6</em> </p><dl><dt class="tparam-name-index-invalid">9&lt;10</dt><dd class="tparam-descr-index-invalid"> bbb</dd></dl><dl><dt class="param-name-index-invalid">a</dt><dd class="param-descr-index-invalid">&lt;8 aaa </dd></dl>] FullCommentAsXML=[<Function file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="6"><Name>comment_to_html_conversion_31</Name><USR>c:@F@comment_to_html_conversion_31#</USR><Declaration>void comment_to_html_conversion_31()</Declaration><Abstract><Para> <emphasized>1&lt;2</emphasized> <emphasized>3&lt;4</emphasized> <emphasized>5&lt;6</emphasized> </Para></Abstract><TemplateParameters><Parameter><Name>9&lt;10</Name><Discussion><Para> bbb</Para></Discussion></Parameter></TemplateParameters><Parameters><Parameter><Identifiers><Identifier><Name>a</Name></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para>&lt;8 aaa </Para></Discussion></Parameter></Parameters></Function>]
 // CHECK-NEXT:  CommentAST=[
 // CHECK-NEXT:    (CXComment_FullComment
 // CHECK-NEXT:       (CXComment_Paragraph
 // CHECK-NEXT:         (CXComment_Text Text=[ ] IsWhitespace)
 // CHECK-NEXT:         (CXComment_InlineCommand CommandName=[a] RenderEmphasized Arg[0]=1<2)
 // CHECK-NEXT:         (CXComment_Text Text=[ ] IsWhitespace)
 // CHECK-NEXT:         (CXComment_InlineCommand CommandName=[e] RenderEmphasized Arg[0]=3<4)
 // CHECK-NEXT:         (CXComment_Text Text=[ ] IsWhitespace)
 // CHECK-NEXT:         (CXComment_InlineCommand CommandName=[em] RenderEmphasized Arg[0]=5<6)
 // CHECK-NEXT:         (CXComment_Text Text=[ ] IsWhitespace))
-// CHECK-NEXT:       (CXComment_ParamCommand in implicitly ParamName=[7<8] ParamIndex=Invalid
+// CHECK-NEXT:       (CXComment_ParamCommand in implicitly ParamName[0]=[a] ParamIndex[0]=Invalid
 // CHECK-NEXT:         (CXComment_Paragraph
-// CHECK-NEXT:           (CXComment_Text Text=[ aaa ])))
+// CHECK-NEXT:           (CXComment_Text Text=[<])
+// CHECK-NEXT:           (CXComment_Text Text=[8 aaa ])))
 // CHECK-NEXT:       (CXComment_TParamCommand ParamName=[9<10] ParamPosition=Invalid
 // CHECK-NEXT:         (CXComment_Paragraph
 // CHECK-NEXT:           (CXComment_Text Text=[ bbb]))))]
 
 /// \\ \@ \& \$ \# \< \> \% \" \. \::
 void comment_to_html_conversion_32();
 
 // CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:6: FunctionDecl=comment_to_html_conversion_32:{{.*}} FullCommentAsHTML=[<p class="para-brief"> \ @ &amp; $ # &lt; &gt; % &quot; . ::</p>] FullCommentAsXML=[<Function file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="6"><Name>comment_to_html_conversion_32</Name><USR>c:@F@comment_to_html_conversion_32#</USR><Declaration>void comment_to_html_conversion_32()</Declaration><Abstract><Para> \ @ &amp; $ # &lt; &gt; % &quot; . ::</Para></Abstract></Function>]
 // CHECK-NEXT:  CommentAST=[

 
 /// Aaa.
 class comment_to_xml_conversion_01 {
 // CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-1]]:7: ClassDecl=comment_to_xml_conversion_01:{{.*}} FullCommentAsXML=[<Class file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-1]]" column="7"><Name>comment_to_xml_conversion_01</Name><USR>c:@S@comment_to_xml_conversion_01</USR><Declaration>class comment_to_xml_conversion_01 {}</Declaration><Abstract><Para> Aaa.</Para></Abstract></Class>]
 
   /// \param aaa Blah blah.
   comment_to_xml_conversion_01(int aaa);
 
-// CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:3: CXXConstructor=comment_to_xml_conversion_01:{{.*}} FullCommentAsXML=[<Function isInstanceMethod="1" file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="3"><Name>comment_to_xml_conversion_01</Name><USR>c:@S@comment_to_xml_conversion_01@F@comment_to_xml_conversion_01#I#</USR><Declaration>comment_to_xml_conversion_01(int aaa)</Declaration><Parameters><Parameter><Name>aaa</Name><Index>0</Index><Direction isExplicit="0">in</Direction><Discussion><Para> Blah blah.</Para></Discussion></Parameter></Parameters></Function>]
+// CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:3: CXXConstructor=comment_to_xml_conversion_01:{{.*}} FullCommentAsXML=[<Function isInstanceMethod="1" file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="3"><Name>comment_to_xml_conversion_01</Name><USR>c:@S@comment_to_xml_conversion_01@F@comment_to_xml_conversion_01#I#</USR><Declaration>comment_to_xml_conversion_01(int aaa)</Declaration><Parameters><Parameter><Identifiers><Identifier><Name>aaa</Name><Index>0</Index></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> Blah blah.</Para></Discussion></Parameter></Parameters></Function>]
 
   /// Aaa.
   ~comment_to_xml_conversion_01();
 
 // CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:3: CXXDestructor=~comment_to_xml_conversion_01:{{.*}} FullCommentAsXML=[<Function isInstanceMethod="1" file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="3"><Name>~comment_to_xml_conversion_01</Name><USR>c:@S@comment_to_xml_conversion_01@F@~comment_to_xml_conversion_01#</USR><Declaration>~comment_to_xml_conversion_01()</Declaration><Abstract><Para> Aaa.</Para></Abstract></Function>]
 
   /// \param aaa Blah blah.
   int comment_to_xml_conversion_02(int aaa);
 
-// CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:7: CXXMethod=comment_to_xml_conversion_02:{{.*}} FullCommentAsXML=[<Function isInstanceMethod="1" file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="7"><Name>comment_to_xml_conversion_02</Name><USR>c:@S@comment_to_xml_conversion_01@F@comment_to_xml_conversion_02#I#</USR><Declaration>int comment_to_xml_conversion_02(int aaa)</Declaration><Parameters><Parameter><Name>aaa</Name><Index>0</Index><Direction isExplicit="0">in</Direction><Discussion><Para> Blah blah.</Para></Discussion></Parameter></Parameters></Function>]
+// CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:7: CXXMethod=comment_to_xml_conversion_02:{{.*}} FullCommentAsXML=[<Function isInstanceMethod="1" file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="7"><Name>comment_to_xml_conversion_02</Name><USR>c:@S@comment_to_xml_conversion_01@F@comment_to_xml_conversion_02#I#</USR><Declaration>int comment_to_xml_conversion_02(int aaa)</Declaration><Parameters><Parameter><Identifiers><Identifier><Name>aaa</Name><Index>0</Index></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> Blah blah.</Para></Discussion></Parameter></Parameters></Function>]
 
   /// \param aaa Blah blah.
   static int comment_to_xml_conversion_03(int aaa);
 
-// CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:14: CXXMethod=comment_to_xml_conversion_03:{{.*}} FullCommentAsXML=[<Function isClassMethod="1" file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="14"><Name>comment_to_xml_conversion_03</Name><USR>c:@S@comment_to_xml_conversion_01@F@comment_to_xml_conversion_03#I#S</USR><Declaration>static int comment_to_xml_conversion_03(int aaa)</Declaration><Parameters><Parameter><Name>aaa</Name><Index>0</Index><Direction isExplicit="0">in</Direction><Discussion><Para> Blah blah.</Para></Discussion></Parameter></Parameters></Function>]
+// CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:14: CXXMethod=comment_to_xml_conversion_03:{{.*}} FullCommentAsXML=[<Function isClassMethod="1" file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="14"><Name>comment_to_xml_conversion_03</Name><USR>c:@S@comment_to_xml_conversion_01@F@comment_to_xml_conversion_03#I#S</USR><Declaration>static int comment_to_xml_conversion_03(int aaa)</Declaration><Parameters><Parameter><Identifiers><Identifier><Name>aaa</Name><Index>0</Index></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> Blah blah.</Para></Discussion></Parameter></Parameters></Function>]
 
   /// Aaa.
   int comment_to_xml_conversion_04;
 
 // CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:7: FieldDecl=comment_to_xml_conversion_04:{{.*}} FullCommentAsXML=[<Variable file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="7"><Name>comment_to_xml_conversion_04</Name><USR>c:@S@comment_to_xml_conversion_01@FI@comment_to_xml_conversion_04</USR><Declaration>int comment_to_xml_conversion_04</Declaration><Abstract><Para> Aaa.</Para></Abstract></Variable>]
 
   /// Aaa.
   static int comment_to_xml_conversion_05;
 
 // CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:14: VarDecl=comment_to_xml_conversion_05:{{.*}} FullCommentAsXML=[<Variable file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="14"><Name>comment_to_xml_conversion_05</Name><USR>c:@S@comment_to_xml_conversion_01@comment_to_xml_conversion_05</USR><Declaration>static int comment_to_xml_conversion_05</Declaration><Abstract><Para> Aaa.</Para></Abstract></Variable>]
 
   /// \param aaa Blah blah.
   void operator()(int aaa);
 
-// CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:8: CXXMethod=operator():{{.*}} FullCommentAsXML=[<Function isInstanceMethod="1" file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="8"><Name>operator()</Name><USR>c:@S@comment_to_xml_conversion_01@F@operator()#I#</USR><Declaration>void operator()(int aaa)</Declaration><Parameters><Parameter><Name>aaa</Name><Index>0</Index><Direction isExplicit="0">in</Direction><Discussion><Para> Blah blah.</Para></Discussion></Parameter></Parameters></Function>]
+// CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:8: CXXMethod=operator():{{.*}} FullCommentAsXML=[<Function isInstanceMethod="1" file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="8"><Name>operator()</Name><USR>c:@S@comment_to_xml_conversion_01@F@operator()#I#</USR><Declaration>void operator()(int aaa)</Declaration><Parameters><Parameter><Identifiers><Identifier><Name>aaa</Name><Index>0</Index></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> Blah blah.</Para></Discussion></Parameter></Parameters></Function>]
 
   /// Aaa.
   operator bool();
 
 // CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:3: CXXConversion=operator bool:{{.*}} FullCommentAsXML=[<Function isInstanceMethod="1" file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="3"><Name>operator bool</Name><USR>c:@S@comment_to_xml_conversion_01@F@operator bool#</USR><Declaration>operator bool()</Declaration><Abstract><Para> Aaa.</Para></Abstract></Function>]
 
   /// Aaa.
   typedef int comment_to_xml_conversion_06;

 // CHECK-NEXT:       (CXComment_BlockCommand CommandName=[throws]
 // CHECK-NEXT:         (CXComment_Paragraph
 // CHECK-NEXT:           (CXComment_Text Text=[ Bbb.] HasTrailingNewline)
 // CHECK-NEXT:           (CXComment_Text Text=[ ] IsWhitespace)))
 // CHECK-NEXT:       (CXComment_BlockCommand CommandName=[throw]
 // CHECK-NEXT:         (CXComment_Paragraph
 // CHECK-NEXT:           (CXComment_Text Text=[ Ccc.]))))]
 
+/// \param aaa xxx
+/// \param bbb Invalid argument
+/// \param ... More arguments
+template<typename T>
+void comment_to_xml_conversion_templated_function(int aaa, ...);
+// CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-1]]:6: FunctionTemplate=comment_to_xml_conversion_templated_function:[[@LINE-1]]:{{.*}} FullCommentAsHTML=[<dl><dt class="param-name-index-0">aaa</dt><dd class="param-descr-index-0"> xxx </dd><dt class="param-name-index-vararg">...</dt><dd class="param-descr-index-vararg"> More arguments</dd><dt class="param-name-index-invalid">bbb</dt><dd class="param-descr-index-invalid"> Invalid argument </dd></dl>] FullCommentAsXML=[<Function templateKind="template" file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-1]]" column="6"><Name>comment_to_xml_conversion_templated_function</Name><USR>c:@FT@&gt;1#Tcomment_to_xml_conversion_templated_function#I.#v#</USR><Declaration>template &lt;typename T&gt;\nvoid comment_to_xml_conversion_templated_function(int aaa, ...)</Declaration><Parameters><Parameter><Identifiers><Identifier><Name>aaa</Name><Index>0</Index></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> xxx </Para></Discussion></Parameter><Parameter><Identifiers><Identifier><Name>...</Name><IsVarArg /></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> More arguments</Para></Discussion></Parameter><Parameter><Identifiers><Identifier><Name>bbb</Name></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> Invalid argument </Para></Discussion></Parameter></Parameters></Function>]
+// CHECK:  CommentAST=[
+// CHECK:    (CXComment_FullComment
+// CHECK:       (CXComment_Paragraph IsWhitespace
+// CHECK:         (CXComment_Text Text=[ ] IsWhitespace))
+// CHECK:       (CXComment_ParamCommand in implicitly ParamName[0]=[aaa] ParamIndex[0]=0
+// CHECK:         (CXComment_Paragraph
+// CHECK:           (CXComment_Text Text=[ xxx] HasTrailingNewline)
+// CHECK:           (CXComment_Text Text=[ ] IsWhitespace)))
+// CHECK:       (CXComment_ParamCommand in implicitly ParamName[0]=[bbb] ParamIndex[0]=Invalid
+// CHECK:         (CXComment_Paragraph
+// CHECK:           (CXComment_Text Text=[ Invalid argument] HasTrailingNewline)
+// CHECK:           (CXComment_Text Text=[ ] IsWhitespace)))
+// CHECK:       (CXComment_ParamCommand in implicitly ParamName[0]=[...] ParamIndex[0]=Variadic
+// CHECK:         (CXComment_Paragraph
+// CHECK:           (CXComment_Text Text=[ More arguments]))))]
+
+/// \param aaa,bbb,... xxx
+template<typename T>
+void comment_to_xml_conversion_templated_function2(int aaa, ...);
+// CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-1]]:6: FunctionTemplate=comment_to_xml_conversion_templated_function2:[[@LINE-1]]:{{.*}}  RawCommentRange=[1092:1 - 1092:27] FullCommentAsHTML=[<dl><dt class="param-name-index-0-invalid-vararg">aaa,bbb,...</dt><dd class="param-descr-index-0-invalid-vararg"> xxx</dd></dl>] FullCommentAsXML=[<Function templateKind="template" file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-1]]" column="6"><Name>comment_to_xml_conversion_templated_function2</Name><USR>c:@FT@&gt;1#Tcomment_to_xml_conversion_templated_function2#I.#v#</USR><Declaration>template &lt;typename T&gt;\nvoid comment_to_xml_conversion_templated_function2(int aaa, ...)</Declaration><Parameters><Parameter><Identifiers><Identifier><Name>aaa</Name><Index>0</Index></Identifier><Identifier><Name>bbb</Name></Identifier><Identifier><Name>...</Name><IsVarArg /></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> xxx</Para></Discussion></Parameter></Parameters></Function>]
+// CHECK:  CommentAST=[
+// CHECK:    (CXComment_FullComment
+// CHECK:       (CXComment_Paragraph IsWhitespace
+// CHECK:         (CXComment_Text Text=[ ] IsWhitespace))
+// CHECK:       (CXComment_ParamCommand in implicitly ParamName[0]=[aaa] ParamName[1]=[bbb] ParamName[2]=[...] ParamIndex[0]=0 ParamIndex[1]=Invalid ParamIndex[2]=Variadic
+// CHECK:         (CXComment_Paragraph
+// CHECK:           (CXComment_Text Text=[ xxx]))))]
+
 #endif
 

clang/test/Index/overriding-ftemplate-comments.cpp

 // RUN: rm -rf %t
 // RUN: mkdir %t
 // RUN: c-index-test -test-load-source all -comments-xml-schema=%S/../../bindings/xml/comment-xml-schema.rng %s > %t/out
 // RUN: FileCheck %s < %t/out
 // Test to search overridden methods for documentation when overriding method has none. rdar://12378793
 
 // Ensure that XML we generate is not invalid.
 // RUN: FileCheck %s -check-prefix=WRONG < %t/out
 // WRONG-NOT: CommentXMLInvalid
 
 /// \tparam
 /// \param AAA Blah blah
 template<typename T>
 void comment_to_html_conversion_17(T AAA);
 
-// CHECK: FullCommentAsXML=[<Function templateKind="template" file="{{[^"]+}}overriding-ftemplate-comments.cpp" line="[[@LINE-2]]" column="6"><Name>comment_to_html_conversion_17</Name><USR>c:@FT@&gt;1#Tcomment_to_html_conversion_17#t0.0#v#</USR><Declaration>template &lt;typename T&gt; void comment_to_html_conversion_17(T AAA)</Declaration><Parameters><Parameter><Name>AAA</Name><Index>0</Index><Direction isExplicit="0">in</Direction><Discussion><Para> Blah blah</Para></Discussion></Parameter></Parameters></Function>]
+// CHECK: FullCommentAsXML=[<Function templateKind="template" file="{{[^"]+}}overriding-ftemplate-comments.cpp" line="[[@LINE-2]]" column="6"><Name>comment_to_html_conversion_17</Name><USR>c:@FT@&gt;1#Tcomment_to_html_conversion_17#t0.0#v#</USR><Declaration>template &lt;typename T&gt; void comment_to_html_conversion_17(T AAA)</Declaration><Parameters><Parameter><Identifiers><Identifier><Name>AAA</Name><Index>0</Index></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> Blah blah</Para></Discussion></Parameter></Parameters></Function>]
 
 template<typename T>
 void comment_to_html_conversion_17(T PPP);
 
-// CHECK: FullCommentAsXML=[<Function templateKind="template" file="{{[^"]+}}overriding-ftemplate-comments.cpp" line="[[@LINE-2]]" column="6"><Name>comment_to_html_conversion_17</Name><USR>c:@FT@&gt;1#Tcomment_to_html_conversion_17#t0.0#v#</USR><Declaration>template &lt;typename T&gt; void comment_to_html_conversion_17(T PPP)</Declaration><Parameters><Parameter><Name>PPP</Name><Index>0</Index><Direction isExplicit="0">in</Direction><Discussion><Para> Blah blah</Para></Discussion></Parameter></Parameters></Function>]
+// CHECK: FullCommentAsXML=[<Function templateKind="template" file="{{[^"]+}}overriding-ftemplate-comments.cpp" line="[[@LINE-2]]" column="6"><Name>comment_to_html_conversion_17</Name><USR>c:@FT@&gt;1#Tcomment_to_html_conversion_17#t0.0#v#</USR><Declaration>template &lt;typename T&gt; void comment_to_html_conversion_17(T PPP)</Declaration><Parameters><Parameter><Identifiers><Identifier><Name>PPP</Name><Index>0</Index></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> Blah blah</Para></Discussion></Parameter></Parameters></Function>]
 
 //===----------------------------------------------------------------------===//
 
 /// \tparam BBB Bbb
 /// \tparam AAA Aaa
 template<typename AAA, typename BBB>
 void comment_to_html_conversion_19(AAA aaa, BBB bbb);
 

clang/test/Index/overriding-method-comments.mm

 
 @interface Root<P>
 /**
  * \param[in] AAA ZZZ
  */
 - (void)METH:(id)AAA;
 @end
 
-// CHECK: FullCommentAsXML=[<Function isInstanceMethod="1" file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-3]]" column="1"><Name>METH:</Name><USR>c:objc(cs)Root(im)METH:</USR><Declaration>- (void)METH:(id)AAA;</Declaration><Parameters><Parameter><Name>AAA</Name><Index>0</Index><Direction isExplicit="1">in</Direction><Discussion><Para> ZZZ</Para></Discussion></Parameter></Parameters></Function>]
+// CHECK: FullCommentAsXML=[<Function isInstanceMethod="1" file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-3]]" column="1"><Name>METH:</Name><USR>c:objc(cs)Root(im)METH:</USR><Declaration>- (void)METH:(id)AAA;</Declaration><Parameters><Parameter><Identifiers><Identifier><Name>AAA</Name><Index>0</Index></Identifier></Identifiers><Direction isExplicit="1">in</Direction><Discussion><Para> ZZZ</Para></Discussion></Parameter></Parameters></Function>]
 
 @interface Sub : Root
 @end
 
 @interface Sub (CAT)
 - (void)METH:(id)BBB;
 @end
 
-// CHECK: FullCommentAsXML=[<Function isInstanceMethod="1" file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-3]]" column="1"><Name>METH:</Name><USR>c:objc(cs)Root(im)METH:</USR><Declaration>- (void)METH:(id)BBB;</Declaration><Parameters><Parameter><Name>BBB</Name><Index>0</Index><Direction isExplicit="1">in</Direction><Discussion><Para> ZZZ</Para></Discussion></Parameter></Parameters></Function>]
+// CHECK: FullCommentAsXML=[<Function isInstanceMethod="1" file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-3]]" column="1"><Name>METH:</Name><USR>c:objc(cs)Root(im)METH:</USR><Declaration>- (void)METH:(id)BBB;</Declaration><Parameters><Parameter><Identifiers><Identifier><Name>BBB</Name><Index>0</Index></Identifier></Identifiers><Direction isExplicit="1">in</Direction><Discussion><Para> ZZZ</Para></Discussion></Parameter></Parameters></Function>]
 
 @implementation Sub(CAT)
 - (void)METH:(id)III {}
 @end
 
-// CHECK: FullCommentAsXML=[<Function isInstanceMethod="1" file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-3]]" column="1"><Name>METH:</Name><USR>c:objc(cs)Root(im)METH:</USR><Declaration>- (void)METH:(id)III;</Declaration><Parameters><Parameter><Name>III</Name><Index>0</Index><Direction isExplicit="1">in</Direction><Discussion><Para> ZZZ</Para></Discussion></Parameter></Parameters></Function>]
+// CHECK: FullCommentAsXML=[<Function isInstanceMethod="1" file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-3]]" column="1"><Name>METH:</Name><USR>c:objc(cs)Root(im)METH:</USR><Declaration>- (void)METH:(id)III;</Declaration><Parameters><Parameter><Identifiers><Identifier><Name>III</Name><Index>0</Index></Identifier></Identifiers><Direction isExplicit="1">in</Direction><Discussion><Para> ZZZ</Para></Discussion></Parameter></Parameters></Function>]
 
 @interface Redec : Root
 @end
 
 @interface Redec()
 /**
  * \param[in] AAA input value
  * \param[out] CCC output value is int
  * \param[in] BBB 2nd input value is double
  */
 - (void)EXT_METH:(id)AAA : (double)BBB : (int)CCC;
 @end
 
-// CHECK: FullCommentAsXML=[<Function isInstanceMethod="1" file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-3]]" column="1"><Name>EXT_METH:::</Name><USR>c:objc(cs)Redec(im)EXT_METH:::</USR><Declaration>- (void)EXT_METH:(id)AAA:(double)BBB:(int)CCC;</Declaration><Parameters><Parameter><Name>AAA</Name><Index>0</Index><Direction isExplicit="1">in</Direction><Discussion><Para> input value </Para></Discussion></Parameter><Parameter><Name>BBB</Name><Index>1</Index><Direction isExplicit="1">in</Direction><Discussion><Para> 2nd input value is double</Para></Discussion></Parameter><Parameter><Name>CCC</Name><Index>2</Index><Direction isExplicit="1">out</Direction><Discussion><Para> output value is int </Para></Discussion></Parameter></Parameters></Function>]
+// CHECK: FullCommentAsXML=[<Function isInstanceMethod="1" file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-3]]" column="1"><Name>EXT_METH:::</Name><USR>c:objc(cs)Redec(im)EXT_METH:::</USR><Declaration>- (void)EXT_METH:(id)AAA:(double)BBB:(int)CCC;</Declaration><Parameters><Parameter><Identifiers><Identifier><Name>AAA</Name><Index>0</Index></Identifier></Identifiers><Direction isExplicit="1">in</Direction><Discussion><Para> input value </Para></Discussion></Parameter><Parameter><Identifiers><Identifier><Name>BBB</Name><Index>1</Index></Identifier></Identifiers><Direction isExplicit="1">in</Direction><Discussion><Para> 2nd input value is double</Para></Discussion></Parameter><Parameter><Identifiers><Identifier><Name>CCC</Name><Index>2</Index></Identifier></Identifiers><Direction isExplicit="1">out</Direction><Discussion><Para> output value is int </Para></Discussion></Parameter></Parameters></Function>]
 
 @implementation Redec
 - (void)EXT_METH:(id)PPP : (double)QQQ : (int)RRR {}
 @end
 
-// CHECK: FullCommentAsXML=[<Function isInstanceMethod="1" file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-3]]" column="1"><Name>EXT_METH:::</Name><USR>c:objc(cs)Redec(im)EXT_METH:::</USR><Declaration>- (void)EXT_METH:(id)PPP:(double)QQQ:(int)RRR;</Declaration><Parameters><Parameter><Name>PPP</Name><Index>0</Index><Direction isExplicit="1">in</Direction><Discussion><Para> input value </Para></Discussion></Parameter><Parameter><Name>QQQ</Name><Index>1</Index><Direction isExplicit="1">in</Direction><Discussion><Para> 2nd input value is double</Para></Discussion></Parameter><Parameter><Name>RRR</Name><Index>2</Index><Direction isExplicit="1">out</Direction><Discussion><Para> output value is int </Para></Discussion></Parameter></Parameters></Function>]
+// CHECK: FullCommentAsXML=[<Function isInstanceMethod="1" file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-3]]" column="1"><Name>EXT_METH:::</Name><USR>c:objc(cs)Redec(im)EXT_METH:::</USR><Declaration>- (void)EXT_METH:(id)PPP:(double)QQQ:(int)RRR;</Declaration><Parameters><Parameter><Identifiers><Identifier><Name>PPP</Name><Index>0</Index></Identifier></Identifiers><Direction isExplicit="1">in</Direction><Discussion><Para> input value </Para></Discussion></Parameter><Parameter><Identifiers><Identifier><Name>QQQ</Name><Index>1</Index></Identifier></Identifiers><Direction isExplicit="1">in</Direction><Discussion><Para> 2nd input value is double</Para></Discussion></Parameter><Parameter><Identifiers><Identifier><Name>RRR</Name><Index>2</Index></Identifier></Identifiers><Direction isExplicit="1">out</Direction><Discussion><Para> output value is int </Para></Discussion></Parameter></Parameters></Function>]
 
 struct Base {
   /// \brief Does something.
   /// \param AAA argument to foo_pure.
   virtual void foo_pure(int AAA) = 0;
 
-// CHECK: FullCommentAsXML=[<Function isInstanceMethod="1" file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-2]]" column="16"><Name>foo_pure</Name><USR>c:@S@Base@F@foo_pure#I#</USR><Declaration>virtual void foo_pure(int AAA) = 0</Declaration><Abstract><Para> Does something. </Para></Abstract><Parameters><Parameter><Name>AAA</Name><Index>0</Index><Direction isExplicit="0">in</Direction><Discussion><Para> argument to foo_pure.</Para></Discussion></Parameter></Parameters></Function>]
+// CHECK: FullCommentAsXML=[<Function isInstanceMethod="1" file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-2]]" column="16"><Name>foo_pure</Name><USR>c:@S@Base@F@foo_pure#I#</USR><Declaration>virtual void foo_pure(int AAA) = 0</Declaration><Abstract><Para> Does something. </Para></Abstract><Parameters><Parameter><Identifiers><Identifier><Name>AAA</Name><Index>0</Index></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> argument to foo_pure.</Para></Discussion></Parameter></Parameters></Function>]
 
   /// \brief Does something.
   /// \param BBB argument to defined virtual.
   virtual void foo_inline(int BBB) {}
 
-// CHECK: FullCommentAsXML=[<Function isInstanceMethod="1" file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-2]]" column="16"><Name>foo_inline</Name><USR>c:@S@Base@F@foo_inline#I#</USR><Declaration>virtual void foo_inline(int BBB)</Declaration><Abstract><Para> Does something. </Para></Abstract><Parameters><Parameter><Name>BBB</Name><Index>0</Index><Direction isExplicit="0">in</Direction><Discussion><Para> argument to defined virtual.</Para></Discussion></Parameter></Parameters></Function>]
+// CHECK: FullCommentAsXML=[<Function isInstanceMethod="1" file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-2]]" column="16"><Name>foo_inline</Name><USR>c:@S@Base@F@foo_inline#I#</USR><Declaration>virtual void foo_inline(int BBB)</Declaration><Abstract><Para> Does something. </Para></Abstract><Parameters><Parameter><Identifiers><Identifier><Name>BBB</Name><Index>0</Index></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> argument to defined virtual.</Para></Discussion></Parameter></Parameters></Function>]
 
   /// \brief Does something.
   /// \param CCC argument to undefined virtual.
   virtual void foo_outofline(int CCC);
 
-// CHECK: FullCommentAsXML=[<Function isInstanceMethod="1" file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-2]]" column="16"><Name>foo_outofline</Name><USR>c:@S@Base@F@foo_outofline#I#</USR><Declaration>virtual void foo_outofline(int CCC)</Declaration><Abstract><Para> Does something. </Para></Abstract><Parameters><Parameter><Name>CCC</Name><Index>0</Index><Direction isExplicit="0">in</Direction><Discussion><Para> argument to undefined virtual.</Para></Discussion></Parameter></Parameters></Function>]
+// CHECK: FullCommentAsXML=[<Function isInstanceMethod="1" file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-2]]" column="16"><Name>foo_outofline</Name><USR>c:@S@Base@F@foo_outofline#I#</USR><Declaration>virtual void foo_outofline(int CCC)</Declaration><Abstract><Para> Does something. </Para></Abstract><Parameters><Parameter><Identifiers><Identifier><Name>CCC</Name><Index>0</Index></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> argument to undefined virtual.</Para></Discussion></Parameter></Parameters></Function>]
 };
 
 void Base::foo_outofline(int RRR) {}
 
-// CHECK: FullCommentAsXML=[<Function isInstanceMethod="1" file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-2]]" column="12"><Name>foo_outofline</Name><USR>c:@S@Base@F@foo_outofline#I#</USR><Declaration>void Base::foo_outofline(int RRR)</Declaration><Abstract><Para> Does something. </Para></Abstract><Parameters><Parameter><Name>RRR</Name><Index>0</Index><Direction isExplicit="0">in</Direction><Discussion><Para> argument to undefined virtual.</Para></Discussion></Parameter></Parameters></Function>]
+// CHECK: FullCommentAsXML=[<Function isInstanceMethod="1" file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-2]]" column="12"><Name>foo_outofline</Name><USR>c:@S@Base@F@foo_outofline#I#</USR><Declaration>void Base::foo_outofline(int RRR)</Declaration><Abstract><Para> Does something. </Para></Abstract><Parameters><Parameter><Identifiers><Identifier><Name>RRR</Name><Index>0</Index></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> argument to undefined virtual.</Para></Discussion></Parameter></Parameters></Function>]
 
 struct Derived : public Base {
   virtual void foo_pure(int PPP);
 
-// CHECK: FullCommentAsXML=[<Function isInstanceMethod="1" file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-2]]" column="16"><Name>foo_pure</Name><USR>c:@S@Base@F@foo_pure#I#</USR><Declaration>virtual void foo_pure(int PPP)</Declaration><Abstract><Para> Does something. </Para></Abstract><Parameters><Parameter><Name>PPP</Name><Index>0</Index><Direction isExplicit="0">in</Direction><Discussion><Para> argument to foo_pure.</Para></Discussion></Parameter></Parameters></Function>]
+// CHECK: FullCommentAsXML=[<Function isInstanceMethod="1" file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-2]]" column="16"><Name>foo_pure</Name><USR>c:@S@Base@F@foo_pure#I#</USR><Declaration>virtual void foo_pure(int PPP)</Declaration><Abstract><Para> Does something. </Para></Abstract><Parameters><Parameter><Identifiers><Identifier><Name>PPP</Name><Index>0</Index></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> argument to foo_pure.</Para></Discussion></Parameter></Parameters></Function>]
 
   virtual void foo_inline(int QQQ) {}
 
-// CHECK: FullCommentAsXML=[<Function isInstanceMethod="1" file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-2]]" column="16"><Name>foo_inline</Name><USR>c:@S@Base@F@foo_inline#I#</USR><Declaration>virtual void foo_inline(int QQQ)</Declaration><Abstract><Para> Does something. </Para></Abstract><Parameters><Parameter><Name>QQQ</Name><Index>0</Index><Direction isExplicit="0">in</Direction><Discussion><Para> argument to defined virtual.</Para></Discussion></Parameter></Parameters></Function>]
+// CHECK: FullCommentAsXML=[<Function isInstanceMethod="1" file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-2]]" column="16"><Name>foo_inline</Name><USR>c:@S@Base@F@foo_inline#I#</USR><Declaration>virtual void foo_inline(int QQQ)</Declaration><Abstract><Para> Does something. </Para></Abstract><Parameters><Parameter><Identifiers><Identifier><Name>QQQ</Name><Index>0</Index></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> argument to defined virtual.</Para></Discussion></Parameter></Parameters></Function>]
 };
 
 /// \brief Does something.
 /// \param DDD a value.
 void foo(int DDD);
 
-// CHECK: FullCommentAsXML=[<Function file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-2]]" column="6"><Name>foo</Name><USR>c:@F@foo#I#</USR><Declaration>void foo(int DDD)</Declaration><Abstract><Para> Does something. </Para></Abstract><Parameters><Parameter><Name>DDD</Name><Index>0</Index><Direction isExplicit="0">in</Direction><Discussion><Para> a value.</Para></Discussion></Parameter></Parameters></Function>]
+// CHECK: FullCommentAsXML=[<Function file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-2]]" column="6"><Name>foo</Name><USR>c:@F@foo#I#</USR><Declaration>void foo(int DDD)</Declaration><Abstract><Para> Does something. </Para></Abstract><Parameters><Parameter><Identifiers><Identifier><Name>DDD</Name><Index>0</Index></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> a value.</Para></Discussion></Parameter></Parameters></Function>]
 
 void foo(int SSS) {}
 
-// CHECK: FullCommentAsXML=[<Function file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-2]]" column="6"><Name>foo</Name><USR>c:@F@foo#I#</USR><Declaration>void foo(int SSS)</Declaration><Abstract><Para> Does something. </Para></Abstract><Parameters><Parameter><Name>SSS</Name><Index>0</Index><Direction isExplicit="0">in</Direction><Discussion><Para> a value.</Para></Discussion></Parameter></Parameters></Function>]
+// CHECK: FullCommentAsXML=[<Function file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-2]]" column="6"><Name>foo</Name><USR>c:@F@foo#I#</USR><Declaration>void foo(int SSS)</Declaration><Abstract><Para> Does something. </Para></Abstract><Parameters><Parameter><Identifiers><Identifier><Name>SSS</Name><Index>0</Index></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> a value.</Para></Discussion></Parameter></Parameters></Function>]
 
 /// \brief Does something.
 /// \param EEE argument to function decl.
 void foo1(int EEE);
 
-// CHECK: FullCommentAsXML=[<Function file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-2]]" column="6"><Name>foo1</Name><USR>c:@F@foo1#I#</USR><Declaration>void foo1(int EEE)</Declaration><Abstract><Para> Does something. </Para></Abstract><Parameters><Parameter><Name>EEE</Name><Index>0</Index><Direction isExplicit="0">in</Direction><Discussion><Para> argument to function decl.</Para></Discussion></Parameter></Parameters></Function>]
+// CHECK: FullCommentAsXML=[<Function file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-2]]" column="6"><Name>foo1</Name><USR>c:@F@foo1#I#</USR><Declaration>void foo1(int EEE)</Declaration><Abstract><Para> Does something. </Para></Abstract><Parameters><Parameter><Identifiers><Identifier><Name>EEE</Name><Index>0</Index></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> argument to function decl.</Para></Discussion></Parameter></Parameters></Function>]
 
 void foo1(int TTT);
 
-// CHECK: FullCommentAsXML=[<Function file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-2]]" column="6"><Name>foo1</Name><USR>c:@F@foo1#I#</USR><Declaration>void foo1(int TTT)</Declaration><Abstract><Para> Does something. </Para></Abstract><Parameters><Parameter><Name>TTT</Name><Index>0</Index><Direction isExplicit="0">in</Direction><Discussion><Para> argument to function decl.</Para></Discussion></Parameter></Parameters></Function>]
+// CHECK: FullCommentAsXML=[<Function file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-2]]" column="6"><Name>foo1</Name><USR>c:@F@foo1#I#</USR><Declaration>void foo1(int TTT)</Declaration><Abstract><Para> Does something. </Para></Abstract><Parameters><Parameter><Identifiers><Identifier><Name>TTT</Name><Index>0</Index></Identifier></Identifiers><Direction isExplicit="0">in</Direction><Discussion><Para> argument to function decl.</Para></Discussion></Parameter></Parameters></Function>]
 
 /// \brief Documentation
 /// \tparam BBB The type, silly.
 /// \tparam AAA The type, silly as well.
 template<typename AAA, typename BBB>
 void foo(AAA, BBB);
 
 // CHECK: FullCommentAsXML=[<Function templateKind="template" file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-2]]" column="6"><Name>foo</Name><USR>c:@FT@&gt;2#T#Tfoo#t0.0#t0.1#v#</USR><Declaration>template &lt;typename AAA, typename BBB&gt; void foo(AAA, BBB)</Declaration><Abstract><Para> Documentation </Para></Abstract><TemplateParameters><Parameter><Name>AAA</Name><Index>0</Index><Discussion><Para> The type, silly as well.</Para></Discussion></Parameter><Parameter><Name>BBB</Name><Index>1</Index><Discussion><Para> The type, silly. </Para></Discussion></Parameter></TemplateParameters></Function>]
 
 template<typename PPP, typename QQQ>
 void foo(PPP, QQQ);
 
 // CHECK: FullCommentAsXML=[<Function templateKind="template" file="{{[^"]+}}overriding-method-comments.mm" line="[[@LINE-2]]" column="6"><Name>foo</Name><USR>c:@FT@&gt;2#T#Tfoo#t0.0#t0.1#v#</USR><Declaration>template &lt;typename PPP, typename QQQ&gt; void foo(PPP, QQQ)</Declaration><Abstract><Para> Documentation </Para></Abstract><TemplateParameters><Parameter><Name>PPP</Name><Index>0</Index><Discussion><Para> The type, silly as well.</Para></Discussion></Parameter><Parameter><Name>QQQ</Name><Index>1</Index><Discussion><Para> The type, silly. </Para></Discussion></Parameter></TemplateParameters></Function>]
 

clang/test/Sema/warn-documentation-fixits.cpp

 // RUN: %clang_cc1 -fsyntax-only -Wdocumentation -Wdocumentation-pedantic -fcomment-block-commands=foobar -verify %s
 // RUN  %clang_cc1 -std=c++11 -fsyntax-only -Wdocumentation -Wdocumentation-pedantic -fcomment-block-commands=foobar -fdiagnostics-parseable-fixits %s 2>&1 | FileCheck -DATTRIBUTE="__attribute__((deprecated))" %s
 // RUN: %clang_cc1 -std=c++14 -fsyntax-only -Wdocumentation -Wdocumentation-pedantic -fcomment-block-commands=foobar -fdiagnostics-parseable-fixits %s 2>&1 | FileCheck --check-prefixes=CHECK,CHECK14 -DATTRIBUTE="[[deprecated]]" %s
 
 // expected-warning@+1 {{parameter 'ZZZZZZZZZZ' not found in the function declaration}} expected-note@+1 {{did you mean 'a'?}}
 /// \param ZZZZZZZZZZ Blah blah.
 int test1(int a);
 
-// expected-warning@+1 {{parameter 'aab' not found in the function declaration}} expected-note@+1 {{did you mean 'aaa'?}}
+// expected-warning@+2 {{parameter 'aab' not found in the function declaration}} expected-note@+2 {{did you mean 'aaa'?}}
+// expected-warning@+2 {{parameter 'bbb' is not documented}}
 /// \param aab Blah blah.
 int test2(int aaa, int bbb);
 
+// expected-warning@+1 {{parameter '..' not found in the function declaration}} expected-note@+1 {{did you mean '...'?}}
+/// \param .. Typo of existing variadic parameter
+void test3(...);
+
+// expected-warning@+1 {{parameter '..' not found in the function declaration}} expected-note@+1 {{did you mean '...'?}}
+/// \param aaa,.. Typo of existing variadic parameter
+void test4(int aaa, ...);
+
 // expected-warning@+1 {{template parameter 'ZZZZZZZZZZ' not found in the template declaration}} expected-note@+1 {{did you mean 'T'?}}
 /// \tparam ZZZZZZZZZZ Aaa
 template<typename T>
-void test3(T aaa);
+void test5(T aaa);
 
 // expected-warning@+1 {{template parameter 'SomTy' not found in the template declaration}} expected-note@+1 {{did you mean 'SomeTy'?}}
 /// \tparam SomTy Aaa
 /// \tparam OtherTy Bbb
 template<typename SomeTy, typename OtherTy>
-void test4(SomeTy aaa, OtherTy bbb);
+void test6(SomeTy aaa, OtherTy bbb);
 
 // expected-warning@+1 {{declaration is marked with '\deprecated' command but does not have a deprecation attribute}} expected-note@+2 {{add a deprecation attribute to the declaration to silence this warning}}
 /// \deprecated
 void test_deprecated_1();
 
 // expected-warning@+1 {{declaration is marked with '\deprecated' command but does not have a deprecation attribute}} expected-note@+2 {{add a deprecation attribute to the declaration to silence this warning}}
 /// \deprecated
 void test_deprecated_2(int a);

 int Bar();
 
 // expected-warning@+2  {{unknown command tag name 'encode'; did you mean 'endcode'?}}
 // expected-warning@+1  {{'\endcode' command does not terminate a verbatim text block}}
 /// \encode PR18051
 int PR18051();
 
 // CHECK: fix-it:"{{.*}}":{6:12-6:22}:"a"
-// CHECK: fix-it:"{{.*}}":{10:12-10:15}:"aaa"
-// CHECK: fix-it:"{{.*}}":{14:13-14:23}:"T"
-// CHECK: fix-it:"{{.*}}":{19:13-19:18}:"SomeTy"
-// CHECK: fix-it:"{{.*}}":{26:1-26:1}:"[[ATTRIBUTE]] "
-// CHECK: fix-it:"{{.*}}":{30:1-30:1}:"[[ATTRIBUTE]] "
-// CHECK: fix-it:"{{.*}}":{35:3-35:3}:"[[ATTRIBUTE]] "
-// CHECK: fix-it:"{{.*}}":{39:3-39:3}:"[[ATTRIBUTE]] "
-// CHECK: fix-it:"{{.*}}":{47:3-47:3}:"[[ATTRIBUTE]] "
-// CHECK: fix-it:"{{.*}}":{51:3-51:3}:"[[ATTRIBUTE]] "
-// CHECK: fix-it:"{{.*}}":{76:3-76:3}:"[[ATTRIBUTE]] "
-// CHECK: fix-it:"{{.*}}":{81:3-81:3}:"[[ATTRIBUTE]] "
-// CHECK14: fix-it:"{{.*}}":{87:3-87:3}:"[[ATTRIBUTE]] "
-// CHECK: fix-it:"{{.*}}":{97:1-97:1}:"MY_ATTR_DEPRECATED "
-// CHECK14: fix-it:"{{.*}}":{104:1-104:1}:"ATTRIBUTE_DEPRECATED "
-// CHECK: fix-it:"{{.*}}":{110:6-110:11}:"return"
-// CHECK: fix-it:"{{.*}}":{114:6-114:11}:"foobar"
-// CHECK: fix-it:"{{.*}}":{123:6-123:12}:"endcode"
+// CHECK: fix-it:"{{.*}}":{11:12-11:15}:"aaa"
+// CHECK: fix-it:"{{.*}}":{15:12-15:14}:"..."
+// CHECK: fix-it:"{{.*}}":{19:16-19:18}:"..."
+// CHECK: fix-it:"{{.*}}":{23:13-23:23}:"T"
+// CHECK: fix-it:"{{.*}}":{28:13-28:18}:"SomeTy"
+// CHECK: fix-it:"{{.*}}":{35:1-35:1}:"[[ATTRIBUTE]] "
+// CHECK: fix-it:"{{.*}}":{39:1-39:1}:"[[ATTRIBUTE]] "
+// CHECK: fix-it:"{{.*}}":{44:3-44:3}:"[[ATTRIBUTE]] "
+// CHECK: fix-it:"{{.*}}":{48:3-48:3}:"[[ATTRIBUTE]] "
+// CHECK: fix-it:"{{.*}}":{56:3-56:3}:"[[ATTRIBUTE]] "
+// CHECK: fix-it:"{{.*}}":{60:3-60:3}:"[[ATTRIBUTE]] "
+// CHECK: fix-it:"{{.*}}":{85:3-85:3}:"[[ATTRIBUTE]] "
+// CHECK: fix-it:"{{.*}}":{90:3-90:3}:"[[ATTRIBUTE]] "
+// CHECK14: fix-it:"{{.*}}":{96:3-96:3}:"[[ATTRIBUTE]] "
+// CHECK: fix-it:"{{.*}}":{106:1-106:1}:"MY_ATTR_DEPRECATED "
+// CHECK14: fix-it:"{{.*}}":{113:1-113:1}:"ATTRIBUTE_DEPRECATED "
+// CHECK: fix-it:"{{.*}}":{119:6-119:11}:"return"
+// CHECK: fix-it:"{{.*}}":{123:6-123:11}:"foobar"
+// CHECK: fix-it:"{{.*}}":{132:6-132:12}:"endcode"

clang/test/Sema/warn-documentation.cpp

 int test_param1_backslash;
 
 // rdar://13066276
 // Check that the diagnostic uses the same command marker as the comment.
 // expected-warning@+1 {{'@param' command used in a comment that is not attached to a function declaration}}
 /// @param a Blah blah.
 int test_param1_at;
 
+// expected-warning@+2 {{'\param' command does not have a valid identifier}}
 // expected-warning@+1 {{empty paragraph passed to '\param' command}}
 /// \param
 /// \param a Blah blah.
 int test_param2(int a);
 
 // expected-warning@+1 {{empty paragraph passed to '\param' command}}
 /// \param a
 int test_param3(int a);

 // expected-warning@+1 {{parameter 'a' not found in the function declaration}}
 /// \param a Blah blah.
 int test_param11();
 
 // expected-warning@+1 {{parameter 'A' not found in the function declaration}} expected-note@+1 {{did you mean 'a'?}}
 /// \param A Blah blah.
 int test_param12(int a);
 
-// expected-warning@+1 {{parameter 'aab' not found in the function declaration}} expected-note@+1 {{did you mean 'aaa'?}}
+// expected-warning@+2 {{parameter 'aab' not found in the function declaration}} expected-note@+2 {{did you mean 'aaa'?}}
+// expected-warning@+2 {{parameter 'bbb' is not documented}}
 /// \param aab Blah blah.
 int test_param13(int aaa, int bbb);
 
 // expected-warning@+2 {{parameter 'aab' not found in the function declaration}} expected-note@+2 {{did you mean 'bbb'?}}
 /// \param aaa Blah blah.
 /// \param aab Blah blah.
 int test_param14(int aaa, int bbb);
 
-// expected-warning@+1 {{parameter 'aab' not found in the function declaration}}
+// expected-warning@+3 {{parameter 'aab' not found in the function declaration}}
+// expected-warning@+3 {{parameter 'bbb' is not documented}}
+// expected-warning@+2 {{parameter 'ccc' is not documented}}
 /// \param aab Blah blah.
 int test_param15(int bbb, int ccc);
 
 // expected-warning@+1 {{parameter 'aab' not found in the function declaration}}
 /// \param aab Ccc.
 /// \param aaa Aaa.
 /// \param bbb Bbb.
 int test_param16(int aaa, int bbb);
 
 // expected-warning@+2 {{parameter 'aab' not found in the function declaration}}
 /// \param aaa Aaa.
 /// \param aab Ccc.
 /// \param bbb Bbb.
 int test_param17(int aaa, int bbb);
 
 // expected-warning@+3 {{parameter 'aab' not found in the function declaration}}
 /// \param aaa Aaa.
 /// \param bbb Bbb.
 /// \param aab Ccc.
 int test_param18(int aaa, int bbb);
 
+// expected-warning@+1 {{'\param' command does not have a valid identifier}}
+/// \param 9aaa xxx
+void test_param_invalid_identifier(int aaa);
+
+// expected-warning@+1 {{'\param' command does not have a valid identifier}}
+/// \param aaa,9aaa xxx
+void test_param_invalid_identifier2(int aaa);
+
+// expected-warning@+1 {{'\param' command's identifier is not properly terminated}}
+/// \param aaa#aaa xxx
+void test_param_identifier_not_terminated(int aaa);
+
+// expected-warning@+1 {{'\param' command's identifier is not properly terminated}}
+/// \param aaa, bbb#aaa xxx
+void test_param_identifier_not_terminated2(int aaa, int bbb);
+
+// expected-warning@+1 {{parameter '..' not found in the function declaration}} expected-note@+1 {{did you mean '...'?}}
+/// \param .. xxx
+void test_param_typo_existing_variadic(...);
+
+// expected-warning@+2 {{parameter '..' not found in the function declaration}} expected-note@+2 {{did you mean '...'?}}
+/// \param aaa xxx
+/// \param .. xxx
+void test_param_typo_existing_variadic2(int aaa, ...);
+
+// expected-warning@+1 {{parameter '..' not found in the function declaration}} expected-note@+1 {{did you mean '...'?}}
+/// \param aaa,.. xxx
+void test_param_typo_existing_variadic3(int aaa, ...);
+
+// expected-warning@+2 {{parameter '..' not found in the function declaration}} expected-note@+2 {{did you mean '...'?}}
+// expected-warning@+2 {{parameter '..' not found in the function declaration}}
+/// \param .. xxx
+/// \param .. xxx
+void test_param_typo_existing_variadic_twice(...);
+
+// expected-warning@+1 {{parameter '..' not found in the function declaration}}
+/// \param .. xxx
+void test_param_typo_non_existing_variadic();
+
+// expected-warning@+2 {{parameter '..' not found in the function declaration}}}
+/// \param aaa xxx
+/// \param .. xxx
+void test_param_typo_non_existing_variadic2(int aaa);
+
+// expected-warning@+1 {{parameter '..' not found in the function declaration}}
+/// \param aaa, .. xxx
+void test_param_typo_non_existing_variadic3(int aaa);
+
+// expected-warning@+4 {{parameter '...' is already documented}} expected-note@+3 {{previous documentation}}
+// expected-warning@+4 {{parameter '...' is already documented}} expected-note@+2 {{previous documentation}}
+/// \param aaa xxx
+/// \param ... xxx
+/// \param ... xxx
+/// \param ... xxx
+void test_param_duplicated_comment_variadic(int aaa, ...);
+
+// expected-warning@+3 {{parameter '...' is already documented}} expected-note@+2 {{previous documentation}}
+// expected-warning@+3 {{parameter '...' is already documented}} expected-note@+1 {{previous documentation}}
+/// \param aaa,... xxx
+/// \param ... xxx
+/// \param ... xxx
+void test_param_duplicated_comment_variadic2(int aaa, ...);
+
+// expected-warning@+2 {{parameter '...' is already documented}} expected-note@+2 {{previous documentation}}
+// expected-warning@+2 {{parameter '...' is already documented}} expected-note@+1 {{previous documentation}}
+/// \param aaa,...,... xxx
+/// \param ... xxx
+void test_param_duplicated_comment_variadic3(int aaa, ...);
+
+// expected-warning@+3 {{parameter '...' is already documented}} expected-note@+2 {{previous documentation}}
+// expected-warning@+3 {{parameter '...' is already documented}} expected-note@+1 {{previous documentation}}
+/// \param ... xxx
+/// \param ... xxx
+/// \param ... xxx
+void test_param_duplicated_comment_variadic4(...);
+
+// expected-warning@+2 {{parameter '...' is already documented}} expected-note@+2 {{previous documentation}}
+// expected-warning@+2 {{parameter '...' is already documented}} expected-note@+1 {{previous documentation}}
+/// \param ...,... xxx
+/// \param ... xxx
+void test_param_duplicated_comment_variadic5(...);
+
+// expected-warning@+2 {{parameter '..' not found in the function declaration}}}
+/// \param aaa,... xxx
+/// \param .. xxx
+void test_param_no_typo_correction_for_documented_variadic(int aaa, ...);
+
+// expected-warning@+2 {{'\param' command does not have a valid identifier}}
+// expected-warning@+1 {{empty paragraph passed to '\param' command}}
+/// \param aaa,
+void test_param_trailing_comma(int aaa);
+
+// expected-warning@+1 {{'\param' command does not have a valid identifier}}
+/// \param aaa,,
+void test_param_double_comma(int aaa);
+
 class C {
-  // expected-warning@+1 {{parameter 'aaa' not found in the function declaration}}
+  // expected-warning@+3 {{parameter 'aaa' not found in the function declaration}}
+  // expected-warning@+3 {{parameter 'bbb' is not documented}}
+  // expected-warning@+2 {{parameter 'ccc' is not documented}}
   /// \param aaa Blah blah.
   C(int bbb, int ccc);
 
-  // expected-warning@+1 {{parameter 'aaa' not found in the function declaration}}
+  // expected-warning@+3 {{parameter 'aaa' not found in the function declaration}}
+  // expected-warning@+3 {{parameter 'bbb' is not documented}}
+  // expected-warning@+2 {{parameter 'ccc' is not documented}}
   /// \param aaa Blah blah.
  int test_param19(int bbb, int ccc);
 };
 
-// expected-warning@+1 {{parameter 'aab' not found in the function declaration}}
+// expected-warning@+3 {{parameter 'aab' not found in the function declaration}}
+// expected-warning@+4 {{parameter 'bbb' is not documented}}
+// expected-warning@+3 {{parameter 'ccc' is not documented}}
 /// \param aab Blah blah.
 template<typename T>
 void test_param20(int bbb, int ccc);
 
 // expected-warning@+3 {{parameter 'a' is already documented}}
 // expected-note@+1 {{previous documentation}}
 /// \param a Aaa.
 /// \param a Aaa.
 int test_param21(int a);
 
-// expected-warning@+4 {{parameter 'x2' is already documented}}
-// expected-note@+2 {{previous documentation}}
+// expected-warning@+4 {{parameter 'x2' is already documented}} expected-note@+3 {{previous documentation}}
+// expected-warning@+4 {{parameter 'x3' is not documented}}
 /// \param x1 Aaa.
 /// \param x2 Bbb.
 /// \param x2 Ccc.
 int test_param22(int x1, int x2, int x3);
 
-// expected-warning@+1 {{empty paragraph passed to '\param' command}}
+// expected-warning@+2 {{empty paragraph passed to '\param' command}}
 /// \param a
 /// \retval 0 Blah blah.
 int test_param23(int a);
 
 //===---
 // Test that we treat typedefs to some non-function types as functions for the
 // purposes of documentation comment parsing.
 //===---

clang/tools/c-index-test/c-index-test.c

case CXComment_ParamCommand:
     case CXCommentParamPassDirection_InOut:
       printf(" in,out");
       break;
     }
     if (clang_ParamCommandComment_isDirectionExplicit(Comment))
       printf(" explicitly");
     else
       printf(" implicitly");
-    PrintCXStringWithPrefixAndDispose(
-        "ParamName",
-        clang_ParamCommandComment_getParamName(Comment));
-    if (clang_ParamCommandComment_isParamIndexValid(Comment))
-      printf(" ParamIndex=%u", clang_ParamCommandComment_getParamIndex(Comment));
+    if ((e = clang_ParamCommandComment_getNumParams(Comment))) {
+      for (i = 0; i != e; ++i) {
+        printf(" ParamName[%u]=[", i);
+        PrintCXStringAndDispose(
+            clang_ParamCommandComment_getParamName(Comment, i));
+        printf("]");
+      }
+      for (i = 0; i != e; ++i) {
+        printf(" ParamIndex[%u]=", i);
+        if (clang_ParamCommandComment_isVarArgParam(Comment, i)) {
+          printf("Variadic");
+        } else if (clang_ParamCommandComment_isParamIndexValid(Comment, i))
+          printf("%u", clang_ParamCommandComment_getParamIndex(Comment, i));
         else
-      printf(" ParamIndex=Invalid");
+          printf("Invalid");
+      }
+    }
     break;
   case CXComment_TParamCommand:
     printf("CXComment_TParamCommand");
     PrintCXStringWithPrefixAndDispose(
         "ParamName",
         clang_TParamCommandComment_getParamName(Comment));
     if (clang_TParamCommandComment_isParamPositionValid(Comment)) {
       printf(" ParamPosition={");

clang/tools/libclang/CXComment.cpp

 CXComment clang_BlockCommandComment_getParagraph(CXComment CXC) {
   const BlockCommandComment *BCC = getASTNodeAs<BlockCommandComment>(CXC);
   if (!BCC)
     return createCXComment(nullptr, nullptr);
 
   return createCXComment(BCC->getParagraph(), CXC.TranslationUnit);
 }
 
-CXString clang_ParamCommandComment_getParamName(CXComment CXC) {
+unsigned clang_ParamCommandComment_getNumParams(CXComment CXC) {
   const ParamCommandComment *PCC = getASTNodeAs<ParamCommandComment>(CXC);
-  if (!PCC || !PCC->hasParamName())
+  if (!PCC)
+    return 0;
+
+  return PCC->getNumParams();
+}
+
+CXString clang_ParamCommandComment_getParamName(CXComment CXC, unsigned Idx) {
+  const ParamCommandComment *PCC = getASTNodeAs<ParamCommandComment>(CXC);
+  if (!PCC || Idx >= PCC->getNumParams())
     return cxstring::createNull();
 
-  return cxstring::createRef(PCC->getParamNameAsWritten());
+  return cxstring::createRef(PCC->getParamName(Idx));
 }
 
-unsigned clang_ParamCommandComment_isParamIndexValid(CXComment CXC) {
+unsigned clang_ParamCommandComment_isParamIndexValid(CXComment CXC,
+                                                     unsigned Idx) {
   const ParamCommandComment *PCC = getASTNodeAs<ParamCommandComment>(CXC);
-  if (!PCC)
+  if (!PCC || Idx >= PCC->getNumParams())
+    return false;
+
+  return PCC->isParamIndexValid(Idx);
+}
+
+unsigned clang_ParamCommandComment_isVarArgParam(CXComment CXC, unsigned Idx) {
+  const ParamCommandComment *PCC = getASTNodeAs<ParamCommandComment>(CXC);
+  if (!PCC || Idx >= PCC->getNumParams())
     return false;
 
-  return PCC->isParamIndexValid();
+  return PCC->isVarArgParam(Idx);
 }
 
-unsigned clang_ParamCommandComment_getParamIndex(CXComment CXC) {
+unsigned clang_ParamCommandComment_getParamIndex(CXComment CXC, unsigned Idx) {
   const ParamCommandComment *PCC = getASTNodeAs<ParamCommandComment>(CXC);
-  if (!PCC || !PCC->isParamIndexValid() || PCC->isVarArgParam())
+  if (!PCC || Idx >= PCC->getNumParams() || !PCC->isParamIndexValid(Idx))
     return ParamCommandComment::InvalidParamIndex;
 
-  return PCC->getParamIndex();
+  return PCC->getParamIndex(Idx);
 }
 
 unsigned clang_ParamCommandComment_isDirectionExplicit(CXComment CXC) {
   const ParamCommandComment *PCC = getASTNodeAs<ParamCommandComment>(CXC);
   if (!PCC)
     return false;
 
   return PCC->isDirectionExplicit();

clang/tools/libclang/libclang.exports

 clang_HTMLStartTagComment_isSelfClosing
 clang_HTMLStartTag_getNumAttrs
 clang_HTMLStartTag_getAttrName
 clang_HTMLStartTag_getAttrValue
 clang_BlockCommandComment_getCommandName
 clang_BlockCommandComment_getNumArgs
 clang_BlockCommandComment_getArgText
 clang_BlockCommandComment_getParagraph
+clang_ParamCommandComment_getNumParams
 clang_ParamCommandComment_getParamName
 clang_ParamCommandComment_isParamIndexValid
+clang_ParamCommandComment_isVarArgParam
 clang_ParamCommandComment_getParamIndex
 clang_ParamCommandComment_isDirectionExplicit
 clang_ParamCommandComment_getDirection
 clang_TParamCommandComment_getParamName
 clang_TParamCommandComment_isParamPositionValid
 clang_TParamCommandComment_getDepth
 clang_TParamCommandComment_getIndex
 clang_TargetInfo_dispose