Vendor import of clang trunk r178860:

http://llvm.org/svn/llvm-project/cfe/trunk@178860

1 files changed, 54 insertions, 48 deletions

diff --git a/include/clang/Frontend/FrontendAction.h b/include/clang/Frontend/FrontendAction.h
index 3283444..c67be92 100644
--- a/include/clang/Frontend/FrontendAction.h
+++ b/include/clang/Frontend/FrontendAction.h
@@ -6,6 +6,14 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
+///
+/// \file
+/// \brief Defines the clang::FrontendAction interface and various convenience
+/// abstract classes (clang::ASTFrontendAction, clang::PluginASTAction,
+/// clang::PreprocessorFrontendAction, and clang::WrapperFrontendAction)
+/// derived from it.
+///
+//===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_FRONTEND_FRONTENDACTION_H
 #define LLVM_CLANG_FRONTEND_FRONTENDACTION_H
@@ -13,8 +21,8 @@
 #include "clang/Basic/LLVM.h"
 #include "clang/Basic/LangOptions.h"
 #include "clang/Frontend/FrontendOptions.h"
-#include "llvm/ADT/StringRef.h"
 #include "llvm/ADT/OwningPtr.h"
+#include "llvm/ADT/StringRef.h"
 #include <string>
 #include <vector>
 
@@ -24,8 +32,7 @@ class ASTMergeAction;
 class ASTUnit;
 class CompilerInstance;
 
-/// FrontendAction - Abstract base class for actions which can be performed by
-/// the frontend.
+/// Abstract base class for actions which can be performed by the frontend.
 class FrontendAction {
   FrontendInputFile CurrentInput;
   OwningPtr<ASTUnit> CurrentASTUnit;
@@ -41,20 +48,19 @@ protected:
   /// @name Implementation Action Interface
   /// @{
 
-  /// CreateASTConsumer - Create the AST consumer object for this action, if
-  /// supported.
+  /// \brief Create the AST consumer object for this action, if supported.
   ///
-  /// This routine is called as part of \see BeginSourceAction(), which will
+  /// This routine is called as part of BeginSourceFile(), which will
   /// fail if the AST consumer cannot be created. This will not be called if the
   /// action has indicated that it only uses the preprocessor.
   ///
-  /// \param CI - The current compiler instance, provided as a convenience, \see
+  /// \param CI - The current compiler instance, provided as a convenience, see
   /// getCompilerInstance().
   ///
-  /// \param InFile - The current input file, provided as a convenience, \see
+  /// \param InFile - The current input file, provided as a convenience, see
   /// getCurrentFile().
   ///
-  /// \return The new AST consumer, or 0 on failure.
+  /// \return The new AST consumer, or null on failure.
   virtual ASTConsumer *CreateASTConsumer(CompilerInstance &CI,
                                          StringRef InFile) = 0;
 
@@ -62,29 +68,29 @@ protected:
   /// opportunity to modify the CompilerInvocation or do some other action
   /// before BeginSourceFileAction is called.
   ///
-  /// \return True on success; on failure \see BeginSourceFileAction() and
-  /// ExecutionAction() and EndSourceFileAction() will not be called.
+  /// \return True on success; on failure BeginSourceFileAction(),
+  /// ExecuteAction() and EndSourceFileAction() will not be called.
   virtual bool BeginInvocation(CompilerInstance &CI) { return true; }
 
-  /// BeginSourceFileAction - Callback at the start of processing a single
-  /// input.
+  /// \brief Callback at the start of processing a single input.
   ///
-  /// \return True on success; on failure \see ExecutionAction() and
+  /// \return True on success; on failure ExecutionAction() and
   /// EndSourceFileAction() will not be called.
   virtual bool BeginSourceFileAction(CompilerInstance &CI,
                                      StringRef Filename) {
     return true;
   }
 
-  /// ExecuteAction - Callback to run the program action, using the initialized
+  /// \brief Callback to run the program action, using the initialized
   /// compiler instance.
   ///
-  /// This routine is guaranteed to only be called between \see
-  /// BeginSourceFileAction() and \see EndSourceFileAction().
+  /// This is guaranteed to only be called between BeginSourceFileAction()
+  /// and EndSourceFileAction().
   virtual void ExecuteAction() = 0;
 
-  /// EndSourceFileAction - Callback at the end of processing a single input;
-  /// this is guaranteed to only be called following a successful call to
+  /// \brief Callback at the end of processing a single input.
+  ///
+  /// This is guaranteed to only be called following a successful call to
   /// BeginSourceFileAction (and BeginSourceFile).
   virtual void EndSourceFileAction() {}
 
@@ -142,34 +148,35 @@ public:
   /// @name Supported Modes
   /// @{
 
-  /// usesPreprocessorOnly - Does this action only use the preprocessor? If so
-  /// no AST context will be created and this action will be invalid with AST
-  /// file inputs.
+  /// \brief Does this action only use the preprocessor?
+  ///
+  /// If so no AST context will be created and this action will be invalid
+  /// with AST file inputs.
   virtual bool usesPreprocessorOnly() const = 0;
 
   /// \brief For AST-based actions, the kind of translation unit we're handling.
   virtual TranslationUnitKind getTranslationUnitKind() { return TU_Complete; }
 
-  /// hasPCHSupport - Does this action support use with PCH?
+  /// \brief Does this action support use with PCH?
   virtual bool hasPCHSupport() const { return !usesPreprocessorOnly(); }
 
-  /// hasASTFileSupport - Does this action support use with AST files?
+  /// \brief Does this action support use with AST files?
   virtual bool hasASTFileSupport() const { return !usesPreprocessorOnly(); }
 
-  /// hasIRSupport - Does this action support use with IR files?
+  /// \brief Does this action support use with IR files?
   virtual bool hasIRSupport() const { return false; }
 
-  /// hasCodeCompletionSupport - Does this action support use with code
-  /// completion?
+  /// \brief Does this action support use with code completion?
   virtual bool hasCodeCompletionSupport() const { return false; }
 
   /// @}
   /// @name Public Action Interface
   /// @{
 
-  /// BeginSourceFile - Prepare the action for processing the input file
-  /// \p Input; this is run after the options and frontend have been
-  /// initialized, but prior to executing any per-file processing.
+  /// \brief Prepare the action for processing the input file \p Input.
+  ///
+  /// This is run after the options and frontend have been initialized,
+  /// but prior to executing any per-file processing.
   ///
   /// \param CI - The compiler instance this action is being run from. The
   /// action may store and use this object up until the matching EndSourceFile
@@ -180,29 +187,28 @@ public:
   /// several objects which would normally be owned by the
   /// CompilerInstance. When processing AST input files, these objects should
   /// generally not be initialized in the CompilerInstance -- they will
-  /// automatically be shared with the AST file in between \see
-  /// BeginSourceFile() and \see EndSourceFile().
+  /// automatically be shared with the AST file in between
+  /// BeginSourceFile() and EndSourceFile().
   ///
   /// \return True on success; on failure the compilation of this file should
-  /// be aborted and neither Execute nor EndSourceFile should be called.
+  /// be aborted and neither Execute() nor EndSourceFile() should be called.
   bool BeginSourceFile(CompilerInstance &CI, const FrontendInputFile &Input);
 
-  /// Execute - Set the source managers main input file, and run the action.
+  /// \brief Set the source manager's main input file, and run the action.
   bool Execute();
 
-  /// EndSourceFile - Perform any per-file post processing, deallocate per-file
+  /// \brief Perform any per-file post processing, deallocate per-file
   /// objects, and run statistics and output file cleanup code.
   void EndSourceFile();
 
   /// @}
 };
 
-/// ASTFrontendAction - Abstract base class to use for AST consumer based
-/// frontend actions.
+/// \brief Abstract base class to use for AST consumer-based frontend actions.
 class ASTFrontendAction : public FrontendAction {
 protected:
-  /// ExecuteAction - Implement the ExecuteAction interface by running Sema on
-  /// the already initialized AST consumer.
+  /// \brief Implement the ExecuteAction interface by running Sema on
+  /// the already-initialized AST consumer.
   ///
   /// This will also take care of instantiating a code completion consumer if
   /// the user requested it and the action supports it.
@@ -219,7 +225,7 @@ protected:
                                          StringRef InFile) = 0;
 
 public:
-  /// ParseArgs - Parse the given plugin command line arguments.
+  /// \brief Parse the given plugin command line arguments.
   ///
   /// \param CI - The compiler instance, for use in reporting diagnostics.
   /// \return True if the parsing succeeded; otherwise the plugin will be
@@ -229,11 +235,10 @@ public:
                          const std::vector<std::string> &arg) = 0;
 };
 
-/// PreprocessorFrontendAction - Abstract base class to use for preprocessor
-/// based frontend actions.
+/// \brief Abstract base class to use for preprocessor-based frontend actions.
 class PreprocessorFrontendAction : public FrontendAction {
 protected:
-  /// CreateASTConsumer - Provide a default implementation which returns aborts,
+  /// \brief Provide a default implementation which returns aborts;
   /// this method should never be called by FrontendAction clients.
   virtual ASTConsumer *CreateASTConsumer(CompilerInstance &CI,
                                          StringRef InFile);
@@ -242,11 +247,12 @@ public:
   virtual bool usesPreprocessorOnly() const { return true; }
 };
 
-/// WrapperFrontendAction - A frontend action which simply wraps some other
-/// runtime specified frontend action. Deriving from this class allows an
-/// action to inject custom logic around some existing action's behavior. It
-/// implements every virtual method in the FrontendAction interface by
-/// forwarding to the wrapped action.
+/// \brief A frontend action which simply wraps some other runtime-specified
+/// frontend action.
+///
+/// Deriving from this class allows an action to inject custom logic around
+/// some existing action's behavior. It implements every virtual method in
+/// the FrontendAction interface by forwarding to the wrapped action.
 class WrapperFrontendAction : public FrontendAction {
   OwningPtr<FrontendAction> WrappedAction;