[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