Documentation cleanup:
* Primarily fixed \param commands with names not matching any actual
  parameters of the documented functions.  In many cases this consists
  just of fixing up the parameter name in the \param to match the code,
  in some it means deleting obsolete documentation and occasionally it
  means documenting the parameter that has replaced the older one that
  was documented, which sometimes means some simple reverse-engineering
  of the docs from the implementation;
* Fixed \param ParamName [out] to the correct format with [out] before
  the parameter name;
* Fixed some \brief summaries.


git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@158980 91177308-0d34-0410-b5e6-96231b3b80d8
diff --git a/include/clang/AST/TemplateBase.h b/include/clang/AST/TemplateBase.h
index 76cbcfb..54c9f2c 100644
--- a/include/clang/AST/TemplateBase.h
+++ b/include/clang/AST/TemplateBase.h
@@ -299,14 +299,12 @@
     return Args.NumArgs;
   }
 
-  /// Determines whether two template arguments are superficially the
+  /// \brief Determines whether two template arguments are superficially the
   /// same.
   bool structurallyEquals(const TemplateArgument &Other) const;
 
-  /// \brief When the template argument is a pack expansion, returns 
+  /// \brief When the template argument is a pack expansion, returns
   /// the pattern of the pack expansion.
-  ///
-  /// \param Ellipsis Will be set to the location of the ellipsis.
   TemplateArgument getPackExpansionPattern() const;
 
   /// \brief Print this template argument to the given output stream.
diff --git a/include/clang/Basic/Diagnostic.h b/include/clang/Basic/Diagnostic.h
index 016628e..883e9d1 100644
--- a/include/clang/Basic/Diagnostic.h
+++ b/include/clang/Basic/Diagnostic.h
@@ -584,9 +584,9 @@
   /// diagnostics (through @c ProcessDiag) when it is destroyed.
   ///
   /// \param DiagID A member of the @c diag::kind enum.
-  /// \param Pos Represents the source location associated with the diagnostic,
+  /// \param Loc Represents the source location associated with the diagnostic,
   /// which can be an invalid location if no position information is available.
-  inline DiagnosticBuilder Report(SourceLocation Pos, unsigned DiagID);
+  inline DiagnosticBuilder Report(SourceLocation Loc, unsigned DiagID);
   inline DiagnosticBuilder Report(unsigned DiagID);
 
   void Report(const StoredDiagnostic &storedDiag);
@@ -975,9 +975,6 @@
   return DB;
 }
 
-/// Report - Issue the message to the client.  DiagID is a member of the
-/// diag::kind enum.  This actually returns a new instance of DiagnosticBuilder
-/// which emits the diagnostics (through ProcessDiag) when it is destroyed.
 inline DiagnosticBuilder DiagnosticsEngine::Report(SourceLocation Loc,
                                             unsigned DiagID){
   assert(CurDiagID == ~0U && "Multiple diagnostics in flight at once!");
diff --git a/include/clang/Frontend/CompilerInvocation.h b/include/clang/Frontend/CompilerInvocation.h
index 1f9a8ab..fc3ab10 100644
--- a/include/clang/Frontend/CompilerInvocation.h
+++ b/include/clang/Frontend/CompilerInvocation.h
@@ -38,10 +38,13 @@
 class ArgList;
 }
 
-/// CompilerInvocation - Fill out Opts based on the options given in Args.
+/// \brief Fill out Opts based on the options given in Args.
+///
 /// Args must have been created from the OptTable returned by
-/// createCC1OptTable(). When errors are encountered, return false and,
-/// if Diags is non-null, report the error(s).
+/// createCC1OptTable().
+///
+/// When errors are encountered, return false and, if Diags is non-null,
+/// report the error(s).
 bool ParseDiagnosticArgs(DiagnosticOptions &Opts, driver::ArgList &Args,
                          DiagnosticsEngine *Diags = 0);
   
@@ -58,8 +61,7 @@
   const LangOptions *getLangOpts() const { return LangOpts.getPtr(); }
 };
   
-/// CompilerInvocation - Helper class for holding the data necessary to invoke
-/// the compiler.
+/// \brief Helper class for holding the data necessary to invoke the compiler.
 ///
 /// This class is designed to represent an abstract "invocation" of the
 /// compiler, including data such as the include paths, the code generation
@@ -103,10 +105,10 @@
   /// @name Utility Methods
   /// @{
 
-  /// CreateFromArgs - Create a compiler invocation from a list of input
-  /// options. Returns true on success.
+  /// \brief Create a compiler invocation from a list of input options.
+  /// \returns true on success.
   ///
-  /// \param Res [out] - The resulting invocation.
+  /// \param [out] Res - The resulting invocation.
   /// \param ArgBegin - The first element in the argument vector.
   /// \param ArgEnd - The last element in the argument vector.
   /// \param Diags - The diagnostic engine to use for errors.
@@ -115,7 +117,7 @@
                              const char* const *ArgEnd,
                              DiagnosticsEngine &Diags);
 
-  /// GetBuiltinIncludePath - Get the directory where the compiler headers
+  /// \brief Get the directory where the compiler headers
   /// reside, relative to the compiler binary (found by the passed in
   /// arguments).
   ///
@@ -125,11 +127,11 @@
   /// executable), for finding the builtin compiler path.
   static std::string GetResourcesPath(const char *Argv0, void *MainAddr);
 
-  /// toArgs - Convert the CompilerInvocation to a list of strings suitable for
+  /// \brief Convert the CompilerInvocation to a list of strings suitable for
   /// passing to CreateFromArgs.
   void toArgs(std::vector<std::string> &Res) const;
 
-  /// setLangDefaults - Set language defaults for the given input language and
+  /// \brief Set language defaults for the given input language and
   /// language standard in this CompilerInvocation.
   ///
   /// \param IK - The input language.
@@ -139,10 +141,10 @@
     setLangDefaults(*getLangOpts(), IK, LangStd);
   }
 
-  /// setLangDefaults - Set language defaults for the given input language and
+  /// \brief Set language defaults for the given input language and
   /// language standard in the given LangOptions object.
   ///
-  /// \param LangOpts - The LangOptions object to set up.
+  /// \param Opts - The LangOptions object to set up.
   /// \param IK - The input language.
   /// \param LangStd - The input language standard.
   static void setLangDefaults(LangOptions &Opts, InputKind IK,
diff --git a/include/clang/Lex/DirectoryLookup.h b/include/clang/Lex/DirectoryLookup.h
index 0976da3..d773fc6 100644
--- a/include/clang/Lex/DirectoryLookup.h
+++ b/include/clang/Lex/DirectoryLookup.h
@@ -146,14 +146,14 @@
   /// part of a known module, this will be set to the module that should
   /// be imported instead of preprocessing/parsing the file found.
   ///
-  /// \param InUserSpecifiedSystemHeader [out] If the file is found, set to true
-  /// if the file is located in a framework that has been user-specified to be
-  /// treated as a system framework.
+  /// \param [out] InUserSpecifiedSystemFramework If the file is found,
+  /// set to true if the file is located in a framework that has been
+  /// user-specified to be treated as a system framework.
   const FileEntry *LookupFile(StringRef Filename, HeaderSearch &HS,
                               SmallVectorImpl<char> *SearchPath,
                               SmallVectorImpl<char> *RelativePath,
                               Module **SuggestedModule,
-                              bool &InUserSpecifiedSystemHeader) const;
+                              bool &InUserSpecifiedSystemFramework) const;
 
 private:
   const FileEntry *DoFrameworkLookup(
diff --git a/include/clang/Lex/HeaderSearch.h b/include/clang/Lex/HeaderSearch.h
index 904d643..df64f2a 100644
--- a/include/clang/Lex/HeaderSearch.h
+++ b/include/clang/Lex/HeaderSearch.h
@@ -424,7 +424,7 @@
   /// \brief Retrieve the name of the module file that should be used to 
   /// load a module with the given name.
   ///
-  /// \param Module The module whose module file name will be returned.
+  /// \param ModuleName The module whose module file name will be returned.
   ///
   /// \returns The name of the module file that corresponds to this module,
   /// or an empty string if this module does not correspond to any module file.
diff --git a/include/clang/Lex/PPCallbacks.h b/include/clang/Lex/PPCallbacks.h
index e7219c7..962b4df 100644
--- a/include/clang/Lex/PPCallbacks.h
+++ b/include/clang/Lex/PPCallbacks.h
@@ -140,7 +140,7 @@
 
   /// \brief Callback invoked when a \#pragma message directive is read.
   /// \param Loc The location of the message directive.
-  /// \param str The text of the message directive.
+  /// \param Str The text of the message directive.
   virtual void PragmaMessage(SourceLocation Loc, StringRef Str) {
   }
 
@@ -177,7 +177,7 @@
   virtual void MacroUndefined(const Token &MacroNameTok, const MacroInfo *MI) {
   }
   
-  /// Defined - This hook is called whenever the 'defined' operator is seen.
+  /// \brief Hook called whenever the 'defined' operator is seen.
   virtual void Defined(const Token &MacroNameTok) {
   }
   
@@ -206,13 +206,13 @@
 
   /// \brief Hook called whenever an \#ifdef is seen.
   /// \param Loc the source location of the directive.
-  /// \param II Information on the token being tested.
+  /// \param MacroNameTok Information on the token being tested.
   virtual void Ifdef(SourceLocation Loc, const Token &MacroNameTok) {
   }
 
   /// \brief Hook called whenever an \#ifndef is seen.
   /// \param Loc the source location of the directive.
-  /// \param II Information on the token being tested.
+  /// \param MacroNameTok Information on the token being tested.
   virtual void Ifndef(SourceLocation Loc, const Token &MacroNameTok) {
   }
 
diff --git a/include/clang/Sema/Initialization.h b/include/clang/Sema/Initialization.h
index 0dd6887..a10b9db 100644
--- a/include/clang/Sema/Initialization.h
+++ b/include/clang/Sema/Initialization.h
@@ -855,8 +855,8 @@
   ///
   /// \param BaseType the base type to which we will be casting.
   ///
-  /// \param IsLValue true if the result of this cast will be treated as 
-  /// an lvalue.
+  /// \param Category Indicates whether the result will be treated as an
+  /// rvalue, an xvalue, or an lvalue.
   void AddDerivedToBaseCastStep(QualType BaseType,
                                 ExprValueKind Category);
      
@@ -865,9 +865,6 @@
   /// \param BindingTemporary True if we are binding a reference to a temporary
   /// object (thereby extending its lifetime); false if we are binding to an
   /// lvalue or an lvalue treated as an rvalue.
-  ///
-  /// \param UnnecessaryCopy True if we should check for a copy
-  /// constructor for a completely unnecessary but
   void AddReferenceBindingStep(QualType T, bool BindingTemporary);
 
   /// \brief Add a new step that makes an extraneous copy of the input
diff --git a/lib/Sema/SemaDecl.cpp b/lib/Sema/SemaDecl.cpp
index f04fc15..aea92a4 100644
--- a/lib/Sema/SemaDecl.cpp
+++ b/lib/Sema/SemaDecl.cpp
@@ -5831,12 +5831,12 @@
 /// that have been instantiated via C++ template instantiation (called
 /// via InstantiateDecl).
 ///
-/// \param IsExplicitSpecialiation whether this new function declaration is
+/// \param IsExplicitSpecialization whether this new function declaration is
 /// an explicit specialization of the previous declaration.
 ///
 /// This sets NewFD->isInvalidDecl() to true if there was an error.
 ///
-/// Returns true if the function declaration is a redeclaration.
+/// \returns true if the function declaration is a redeclaration.
 bool Sema::CheckFunctionDeclaration(Scope *S, FunctionDecl *NewFD,
                                     LookupResult &Previous,
                                     bool IsExplicitSpecialization) {
diff --git a/lib/Sema/SemaExprObjC.cpp b/lib/Sema/SemaExprObjC.cpp
index 9466f41..5304f56 100644
--- a/lib/Sema/SemaExprObjC.cpp
+++ b/lib/Sema/SemaExprObjC.cpp
@@ -1940,9 +1940,9 @@
 ///
 /// \param LBracLoc The location of the opening square bracket ']'.
 ///
-/// \param RBrac The location of the closing square bracket ']'.
+/// \param RBracLoc The location of the closing square bracket ']'.
 ///
-/// \param Args The message arguments.
+/// \param ArgsIn The message arguments.
 ExprResult Sema::BuildClassMessage(TypeSourceInfo *ReceiverTypeInfo,
                                    QualType ReceiverType,
                                    SourceLocation SuperLoc,
@@ -2110,9 +2110,9 @@
 ///
 /// \param LBracLoc The location of the opening square bracket ']'.
 ///
-/// \param RBrac The location of the closing square bracket ']'.
+/// \param RBracLoc The location of the closing square bracket ']'.
 ///
-/// \param Args The message arguments.
+/// \param ArgsIn The message arguments.
 ExprResult Sema::BuildInstanceMessage(Expr *Receiver,
                                       QualType ReceiverType,
                                       SourceLocation SuperLoc,
diff --git a/lib/Sema/SemaOverload.cpp b/lib/Sema/SemaOverload.cpp
index 013af8a..0f23a66 100644
--- a/lib/Sema/SemaOverload.cpp
+++ b/lib/Sema/SemaOverload.cpp
@@ -7826,13 +7826,11 @@
 /// \brief Computes the best viable function (C++ 13.3.3)
 /// within an overload candidate set.
 ///
-/// \param CandidateSet the set of candidate functions.
-///
-/// \param Loc the location of the function name (or operator symbol) for
+/// \param Loc The location of the function name (or operator symbol) for
 /// which overload resolution occurs.
 ///
-/// \param Best f overload resolution was successful or found a deleted
-/// function, Best points to the candidate function found.
+/// \param Best If overload resolution was successful or found a deleted
+/// function, \p Best points to the candidate function found.
 ///
 /// \returns The result of overload resolution.
 OverloadingResult
diff --git a/lib/Sema/SemaType.cpp b/lib/Sema/SemaType.cpp
index 4bd9b14..35019b5 100644
--- a/lib/Sema/SemaType.cpp
+++ b/lib/Sema/SemaType.cpp
@@ -1231,9 +1231,7 @@
 ///
 /// \param ArraySize Expression describing the size of the array.
 ///
-/// \param Loc The location of the entity whose type involves this
-/// array type or, if there is no such entity, the location of the
-/// type that will have array type.
+/// \param Brackets The range from the opening '[' to the closing ']'.
 ///
 /// \param Entity The name of the entity that involves the array
 /// type, if known.
@@ -1593,7 +1591,7 @@
 ///
 /// \param T The type to which we'll be building a block pointer.
 ///
-/// \param CVR The cvr-qualifiers to be applied to the block pointer type.
+/// \param Loc The source location, used for diagnostics.
 ///
 /// \param Entity The name of the entity that involves the block pointer
 /// type, if known.