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
This commit is contained in:
James Dennett
parent
706eedb1b9
commit
f8317679cb
|
|
@ -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<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
|
||||
/// \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<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;
|
||||
|
||||
|
|
|
|||
|
|
@ -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();
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue