Doxygenize the documentation comments
There were many // comment used to document classes, functions etc. but
those are not picked up by doxygen which expects /// comments. This
converts many comments from // to /// in order to improve the generated
documentation.
BUG=
R=jvoung@chromium.org, kschimpf@google.com
Review URL: https://codereview.chromium.org/1216963007.
diff --git a/src/IceCfg.h b/src/IceCfg.h
index 800bf40..08b4e97 100644
--- a/src/IceCfg.h
+++ b/src/IceCfg.h
@@ -6,10 +6,11 @@
// License. See LICENSE.TXT for details.
//
//===----------------------------------------------------------------------===//
-//
-// This file declares the Cfg class, which represents the control flow
-// graph and the overall per-function compilation context.
-//
+///
+/// \file
+/// This file declares the Cfg class, which represents the control flow
+/// graph and the overall per-function compilation context.
+///
//===----------------------------------------------------------------------===//
#ifndef SUBZERO_SRC_ICECFG_H
@@ -35,12 +36,12 @@
uint32_t SequenceNumber) {
return std::unique_ptr<Cfg>(new Cfg(Ctx, SequenceNumber));
}
- // Gets a pointer to the current thread's Cfg.
+ /// Gets a pointer to the current thread's Cfg.
static const Cfg *getCurrentCfg() { return ICE_TLS_GET_FIELD(CurrentCfg); }
static void setCurrentCfg(const Cfg *Func) {
ICE_TLS_SET_FIELD(CurrentCfg, Func);
}
- // Gets a pointer to the current thread's Cfg's allocator.
+ /// Gets a pointer to the current thread's Cfg's allocator.
static ArenaAllocator<> *getCurrentCfgAllocator() {
assert(ICE_TLS_GET_FIELD(CurrentCfg));
return ICE_TLS_GET_FIELD(CurrentCfg)->Allocator.get();
@@ -49,44 +50,54 @@
GlobalContext *getContext() const { return Ctx; }
uint32_t getSequenceNumber() const { return SequenceNumber; }
- // Returns true if any of the specified options in the verbose mask
- // are set. If the argument is omitted, it checks if any verbose
- // options at all are set.
+ /// Returns true if any of the specified options in the verbose mask
+ /// are set. If the argument is omitted, it checks if any verbose
+ /// options at all are set.
bool isVerbose(VerboseMask Mask = IceV_All) const { return VMask & Mask; }
void setVerbose(VerboseMask Mask) { VMask = Mask; }
- // Manage the name and return type of the function being translated.
+ /// \name Manage the name and return type of the function being translated.
+ /// @{
void setFunctionName(const IceString &Name) { FunctionName = Name; }
IceString getFunctionName() const { return FunctionName; }
void setReturnType(Type Ty) { ReturnType = Ty; }
+ /// @}
- // Manage the "internal" attribute of the function.
+ /// \name Manage the "internal" attribute of the function.
+ /// @{
void setInternal(bool Internal) { IsInternalLinkage = Internal; }
bool getInternal() const { return IsInternalLinkage; }
+ /// @}
- // Translation error flagging. If support for some construct is
- // known to be missing, instead of an assertion failure, setError()
- // should be called and the error should be propagated back up.
- // This way, we can gracefully fail to translate and let a fallback
- // translator handle the function.
+ /// \name Manage errors.
+ /// @{
+
+ /// Translation error flagging. If support for some construct is
+ /// known to be missing, instead of an assertion failure, setError()
+ /// should be called and the error should be propagated back up.
+ /// This way, we can gracefully fail to translate and let a fallback
+ /// translator handle the function.
void setError(const IceString &Message);
bool hasError() const { return HasError; }
IceString getError() const { return ErrorMessage; }
+ /// @}
- // Manage nodes (a.k.a. basic blocks, CfgNodes).
+ /// \name Manage nodes (a.k.a. basic blocks, CfgNodes).
+ /// @{
void setEntryNode(CfgNode *EntryNode) { Entry = EntryNode; }
CfgNode *getEntryNode() const { return Entry; }
- // Create a node and append it to the end of the linearized list.
+ /// Create a node and append it to the end of the linearized list.
CfgNode *makeNode();
SizeT getNumNodes() const { return Nodes.size(); }
const NodeList &getNodes() const { return Nodes; }
+ /// @}
typedef int32_t IdentifierIndexType;
- // Adds a name to the list and returns its index, suitable for the
- // argument to getIdentifierName(). No checking for duplicates is
- // done. This is generally used for node names and variable names
- // to avoid embedding a std::string inside an arena-allocated
- // object.
+ /// Adds a name to the list and returns its index, suitable for the
+ /// argument to getIdentifierName(). No checking for duplicates is
+ /// done. This is generally used for node names and variable names
+ /// to avoid embedding a std::string inside an arena-allocated
+ /// object.
IdentifierIndexType addIdentifierName(const IceString &Name) {
IdentifierIndexType Index = IdentifierNames.size();
IdentifierNames.push_back(Name);
@@ -97,13 +108,17 @@
}
enum { IdentifierIndexInvalid = -1 };
- // Manage instruction numbering.
+ /// \name Manage instruction numbering.
+ /// @{
InstNumberT newInstNumber() { return NextInstNumber++; }
InstNumberT getNextInstNumber() const { return NextInstNumber; }
+ /// @}
- // Manage Variables.
- // Create a new Variable with a particular type and an optional
- // name. The Node argument is the node where the variable is defined.
+ /// \name Manage Variables.
+ /// @{
+
+ /// Create a new Variable with a particular type and an optional
+ /// name. The Node argument is the node where the variable is defined.
// TODO(jpp): untemplate this with two separate methods: makeVariable and
// makeSpillVariable.
template <typename T = Variable> T *makeVariable(Type Ty) {
@@ -114,15 +129,19 @@
}
SizeT getNumVariables() const { return Variables.size(); }
const VarList &getVariables() const { return Variables; }
+ /// @}
- // Manage arguments to the function.
+ /// \name Manage arguments to the function.
+ /// @{
void addArg(Variable *Arg);
const VarList &getArgs() const { return Args; }
VarList &getArgs() { return Args; }
void addImplicitArg(Variable *Arg);
const VarList &getImplicitArgs() const { return ImplicitArgs; }
+ /// @}
- // Miscellaneous accessors.
+ /// \name Miscellaneous accessors.
+ /// @{
TargetLowering *getTarget() const { return Target.get(); }
VariablesMetadata *getVMetadata() const { return VMetadata.get(); }
Liveness *getLiveness() const { return Live.get(); }
@@ -136,16 +155,17 @@
bool hasComputedFrame() const;
bool getFocusedTiming() const { return FocusedTiming; }
void setFocusedTiming() { FocusedTiming = true; }
+ /// @}
- // Returns true if Var is a global variable that is used by the profiling
- // code.
+ /// Returns true if Var is a global variable that is used by the profiling
+ /// code.
static bool isProfileGlobal(const VariableDeclaration &Var);
- // Passes over the CFG.
+ /// Passes over the CFG.
void translate();
- // After the CFG is fully constructed, iterate over the nodes and
- // compute the predecessor and successor edges, in the form of
- // CfgNode::InEdges[] and CfgNode::OutEdges[].
+ /// After the CFG is fully constructed, iterate over the nodes and
+ /// compute the predecessor and successor edges, in the form of
+ /// CfgNode::InEdges[] and CfgNode::OutEdges[].
void computeInOutEdges();
void renumberInstructions();
void placePhiLoads();
@@ -164,11 +184,14 @@
void contractEmptyNodes();
void doBranchOpt();
- // Manage the CurrentNode field, which is used for validating the
- // Variable::DefNode field during dumping/emitting.
+ /// \name Manage the CurrentNode field.
+ /// CurrentNode is used for validating the Variable::DefNode field during
+ /// dumping/emitting.
+ /// @{
void setCurrentNode(const CfgNode *Node) { CurrentNode = Node; }
void resetCurrentNode() { setCurrentNode(nullptr); }
const CfgNode *getCurrentNode() const { return CurrentNode; }
+ /// @}
void emit();
void emitIAS();
@@ -176,20 +199,20 @@
const Assembler *Asm);
void dump(const IceString &Message = "");
- // Allocate data of type T using the per-Cfg allocator.
+ /// Allocate data of type T using the per-Cfg allocator.
template <typename T> T *allocate() { return Allocator->Allocate<T>(); }
- // Allocate an array of data of type T using the per-Cfg allocator.
+ /// Allocate an array of data of type T using the per-Cfg allocator.
template <typename T> T *allocateArrayOf(size_t NumElems) {
return Allocator->Allocate<T>(NumElems);
}
- // Deallocate data that was allocated via allocate<T>().
+ /// Deallocate data that was allocated via allocate<T>().
template <typename T> void deallocate(T *Object) {
Allocator->Deallocate(Object);
}
- // Deallocate data that was allocated via allocateArrayOf<T>().
+ /// Deallocate data that was allocated via allocateArrayOf<T>().
template <typename T> void deallocateArrayOf(T *Array) {
Allocator->Deallocate(Array);
}
@@ -197,17 +220,17 @@
private:
Cfg(GlobalContext *Ctx, uint32_t SequenceNumber);
- // Adds a call to the ProfileSummary runtime function as the first instruction
- // in this CFG's entry block.
+ /// Adds a call to the ProfileSummary runtime function as the first
+ /// instruction in this CFG's entry block.
void addCallToProfileSummary();
- // Iterates over the basic blocks in this CFG, adding profiling code to each
- // one of them. It returns a list with all the globals that the profiling code
- // needs to be defined.
+ /// Iterates over the basic blocks in this CFG, adding profiling code to each
+ /// one of them. It returns a list with all the globals that the profiling
+ /// code needs to be defined.
void profileBlocks();
GlobalContext *Ctx;
- uint32_t SequenceNumber; // output order for emission
+ uint32_t SequenceNumber; /// output order for emission
VerboseMask VMask;
IceString FunctionName = "";
Type ReturnType = IceType_void;
@@ -215,31 +238,31 @@
bool HasError = false;
bool FocusedTiming = false;
IceString ErrorMessage = "";
- CfgNode *Entry = nullptr; // entry basic block
- NodeList Nodes; // linearized node list; Entry should be first
+ CfgNode *Entry = nullptr; /// entry basic block
+ NodeList Nodes; /// linearized node list; Entry should be first
std::vector<IceString> IdentifierNames;
InstNumberT NextInstNumber;
VarList Variables;
- VarList Args; // subset of Variables, in argument order
- VarList ImplicitArgs; // subset of Variables
+ VarList Args; /// subset of Variables, in argument order
+ VarList ImplicitArgs; /// subset of Variables
std::unique_ptr<ArenaAllocator<>> Allocator;
std::unique_ptr<Liveness> Live;
std::unique_ptr<TargetLowering> Target;
std::unique_ptr<VariablesMetadata> VMetadata;
std::unique_ptr<Assembler> TargetAssembler;
- // Globals required by this CFG. Mostly used for the profiler's globals.
+ /// Globals required by this CFG. Mostly used for the profiler's globals.
std::unique_ptr<VariableDeclarationList> GlobalInits;
- // CurrentNode is maintained during dumping/emitting just for
- // validating Variable::DefNode. Normally, a traversal over
- // CfgNodes maintains this, but before global operations like
- // register allocation, resetCurrentNode() should be called to avoid
- // spurious validation failures.
+ /// CurrentNode is maintained during dumping/emitting just for
+ /// validating Variable::DefNode. Normally, a traversal over
+ /// CfgNodes maintains this, but before global operations like
+ /// register allocation, resetCurrentNode() should be called to avoid
+ /// spurious validation failures.
const CfgNode *CurrentNode = nullptr;
- // Maintain a pointer in TLS to the current Cfg being translated.
- // This is primarily for accessing its allocator statelessly, but
- // other uses are possible.
+ /// Maintain a pointer in TLS to the current Cfg being translated.
+ /// This is primarily for accessing its allocator statelessly, but
+ /// other uses are possible.
ICE_TLS_DECLARE_FIELD(const Cfg *, CurrentCfg);
public:
