[cfe-commits] r173213 - in /cfe/trunk: include/clang/Frontend/FrontendAction.h lib/Frontend/FrontendAction.cpp

James Dennett jdennett at google.com
Tue Jan 22 16:45:44 PST 2013


Author: jdennett
Date: Tue Jan 22 18:45:44 2013
New Revision: 173213

URL: http://llvm.org/viewvc/llvm-project?rev=173213&view=rev
Log:
Documentation cleanup: fixing documentation for FrontendAction.
* Fix a typo, s/BeginSourceAction/BeginSourceFile/, so that the documentation
  for FrontendAction::BeginSourceFileAction links correctly to BeginSourceFile;
* Add some basic \file documentation for FrontendAction.h;
* More use of "\brief" instead of repeating the name of the entity being
  documented;
* Stop using Doxygen-style "///" comments in FrontendAction.cpp, as they were
  polluting the documentation for BeginSourceFile;
* Drop incorrect "\see" markup that broke Doxygen's formatting;
* Other minor documentation fixes.

Modified:
    cfe/trunk/include/clang/Frontend/FrontendAction.h
    cfe/trunk/lib/Frontend/FrontendAction.cpp

Modified: cfe/trunk/include/clang/Frontend/FrontendAction.h
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Frontend/FrontendAction.h?rev=173213&r1=173212&r2=173213&view=diff
==============================================================================
--- cfe/trunk/include/clang/Frontend/FrontendAction.h (original)
+++ cfe/trunk/include/clang/Frontend/FrontendAction.h Tue Jan 22 18:45:44 2013
@@ -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
@@ -24,8 +32,7 @@
 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 @@
   /// @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 @@
   /// opportunity to modify the CompilerInvocation or do some other action
   /// before BeginSourceFileAction is called.
   ///
-  /// \return True on success; on failure \see BeginSourceFileAction() and
+  /// \return True on success; on failure BeginSourceFileAction(),
   /// ExecutionAction() 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 @@
   /// @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 @@
   /// 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 @@
                                          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 @@
                          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 @@
   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;
 

Modified: cfe/trunk/lib/Frontend/FrontendAction.cpp
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/lib/Frontend/FrontendAction.cpp?rev=173213&r1=173212&r2=173213&view=diff
==============================================================================
--- cfe/trunk/lib/Frontend/FrontendAction.cpp (original)
+++ cfe/trunk/lib/Frontend/FrontendAction.cpp Tue Jan 22 18:45:44 2013
@@ -198,7 +198,7 @@
     if (!BeginSourceFileAction(CI, InputFile))
       goto failure;
 
-    /// Create the AST consumer.
+    // Create the AST consumer.
     CI.setASTConsumer(CreateWrappedASTConsumer(CI, InputFile));
     if (!CI.hasASTConsumer())
       goto failure;
@@ -279,8 +279,8 @@
   if (!BeginSourceFileAction(CI, InputFile))
     goto failure;
 
-  /// Create the AST context and consumer unless this is a preprocessor only
-  /// action.
+  // Create the AST context and consumer unless this is a preprocessor only
+  // action.
   if (!usesPreprocessorOnly()) {
     CI.createASTContext();
 





More information about the cfe-commits mailing list