From f8317679cb2dab9d06835e05bd5d69c0bd8f491f Mon Sep 17 00:00:00 2001 From: James Dennett Date: Wed, 23 Jan 2013 00:45:44 +0000 Subject: [PATCH] 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. llvm-svn: 173213 --- clang/include/clang/Frontend/FrontendAction.h | 98 ++++++++++++++------------- clang/lib/Frontend/FrontendAction.cpp | 6 +- 2 files changed, 55 insertions(+), 49 deletions(-) diff --git a/clang/include/clang/Frontend/FrontendAction.h b/clang/include/clang/Frontend/FrontendAction.h index 673aea0..75a8022 100644 --- a/clang/include/clang/Frontend/FrontendAction.h +++ b/clang/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 @@ -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 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 + /// \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 @@ 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 &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 WrappedAction; diff --git a/clang/lib/Frontend/FrontendAction.cpp b/clang/lib/Frontend/FrontendAction.cpp index 9ff7a66..742caf1 100644 --- a/clang/lib/Frontend/FrontendAction.cpp +++ b/clang/lib/Frontend/FrontendAction.cpp @@ -198,7 +198,7 @@ bool FrontendAction::BeginSourceFile(CompilerInstance &CI, 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 @@ bool FrontendAction::BeginSourceFile(CompilerInstance &CI, 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(); -- 2.7.4