[llvm-commits] [hlvm] r38191 - in /hlvm/trunk/hlvm/AST: AST.h Block.h Bundle.h Conditionable.h Constant.h Constants.h ContainerType.h
Reid Spencer
reid at x10sys.com
Sat Jul 7 17:00:58 PDT 2007
Author: reid
Date: Sat Jul 7 19:00:58 2007
New Revision: 38191
URL: http://llvm.org/viewvc/llvm-project?rev=38191&view=rev
Log:
Improve doxygen documentation comments in preparation for the 0.1 release.
Removed:
hlvm/trunk/hlvm/AST/Conditionable.h
Modified:
hlvm/trunk/hlvm/AST/AST.h
hlvm/trunk/hlvm/AST/Block.h
hlvm/trunk/hlvm/AST/Bundle.h
hlvm/trunk/hlvm/AST/Constant.h
hlvm/trunk/hlvm/AST/Constants.h
hlvm/trunk/hlvm/AST/ContainerType.h
Modified: hlvm/trunk/hlvm/AST/AST.h
URL: http://llvm.org/viewvc/llvm-project/hlvm/trunk/hlvm/AST/AST.h?rev=38191&r1=38190&r2=38191&view=diff
==============================================================================
--- hlvm/trunk/hlvm/AST/AST.h (original)
+++ hlvm/trunk/hlvm/AST/AST.h Sat Jul 7 19:00:58 2007
@@ -38,8 +38,8 @@
#include <vector>
/// This namespace is for all HLVM software. It ensures that HLVM software does
-/// not collide with any other software. Hopefully HLVM is not a namespace used
-/// elsewhere.
+/// not collide with any other software. Hopefully "hlvm" is not a namespace
+/// used elsewhere.
namespace hlvm
{
@@ -63,9 +63,12 @@
class CloseOp;
class WriteOp;
-/// This class is used to hold or contain an Abstract Syntax Tree. It provides
-/// those aspects of the tree that are not part of the tree itself.
-/// @brief AST Container Class
+/// This class is used to hold or contain an Abstract Syntax Tree. It forms the
+/// root node of a multi-way tree of other nodes. As such, its parent node is
+/// null and this is only true of the AST node. AST provides a number of
+/// facilities for management of the tree as a whole. It also provides all the
+/// factory functions for creating AST nodes.
+/// @brief AST Tree Root Class
class AST : public Node
{
/// @name Types
@@ -511,5 +514,5 @@
/// @}
};
-} // hlvm
+} // env hlvm namespace
#endif
Modified: hlvm/trunk/hlvm/AST/Block.h
URL: http://llvm.org/viewvc/llvm-project/hlvm/trunk/hlvm/AST/Block.h?rev=38191&r1=38190&r2=38191&view=diff
==============================================================================
--- hlvm/trunk/hlvm/AST/Block.h (original)
+++ hlvm/trunk/hlvm/AST/Block.h Sat Jul 7 19:00:58 2007
@@ -38,12 +38,13 @@
class AutoVarOp;
-/// This class represents an Variable in the HLVM Abstract Syntax Tree.
-/// A Variable is a storage location of a specific type. It can either be
-/// global or local, depending on its parent. Global variables are always
-/// contained in a Bundle. Local variables are always contained in a
-/// Function.
-/// @brief HLVM AST Variable Node
+/// This class represents an block of operators in the HLVM Abstract Syntax
+/// Tree. A block is simply a sequential list of Operator nodes that are
+/// executed in sequence. Block itself is an operator. Its result value is
+/// the value of the last operator executed. As such, blocks can be nested
+/// within blocks. Blocks are used as the operands of the control flow
+/// operators as well.
+/// @brief AST Block Node
class Block : public MultiOperator
{
/// @name Constructors
Modified: hlvm/trunk/hlvm/AST/Bundle.h
URL: http://llvm.org/viewvc/llvm-project/hlvm/trunk/hlvm/AST/Bundle.h?rev=38191&r1=38190&r2=38191&view=diff
==============================================================================
--- hlvm/trunk/hlvm/AST/Bundle.h (original)
+++ hlvm/trunk/hlvm/AST/Bundle.h Sat Jul 7 19:00:58 2007
@@ -40,12 +40,15 @@
class Variable;
class Function;
-/// This class represents an HLVM Bundle. A Bundle is simply a collection of
-/// declarations and definitions. It is the root of the AST tree and also
-/// the grouping and namespace construct in HLVM. Every compilation unit is
-/// a Bundle. Bundles can also be nested in other Bundles. All programming
-/// constructs are defined as child nodes of some Bundle.
-/// @brief HLVM AST Bundle Node
+/// This class is simply a collection of definitions. Things that can be
+/// defined in a bundle include types, global variables, functions, classes,
+/// etc. A bundle is the unit of linking and loading. A given compilation unit
+/// may define as many bundles as it desires. When a bundle is loaded, all of
+/// its definitions become active. Only those things defined in a bundle
+/// participate in linking A Bundle's parent is always the AST node. Each
+/// Bundle has a name and that name forms a namespace for the definitions
+/// within the bundle. Bundles cannot be nested.
+/// @brief AST Bundle Node
class Bundle : public Documentable
{
/// @name Types
@@ -133,5 +136,5 @@
friend class AST;
};
-} // hlvm
+} // end hlvm namespace
#endif
Removed: hlvm/trunk/hlvm/AST/Conditionable.h
URL: http://llvm.org/viewvc/llvm-project/hlvm/trunk/hlvm/AST/Conditionable.h?rev=38190&view=auto
==============================================================================
--- hlvm/trunk/hlvm/AST/Conditionable.h (original)
+++ hlvm/trunk/hlvm/AST/Conditionable.h (removed)
@@ -1,67 +0,0 @@
-//===-- AST Conditionable Class ---------------------------------*- C++ -*-===//
-//
-// High Level Virtual Machine (HLVM)
-//
-// Copyright (C) 2006 Reid Spencer. All Rights Reserved.
-//
-// This software is free software; you can redistribute it and/or modify it
-// under the terms of the GNU Lesser General Public License as published by
-// the Free Software Foundation; either version 2.1 of the License, or (at
-// your option) any later version.
-//
-// This software is distributed in the hope that it will be useful, but WITHOUT
-// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
-// FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
-// more details.
-//
-// You should have received a copy of the GNU Lesser General Public License
-// along with this library in the file named LICENSE.txt; if not, write to the
-// Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
-// MA 02110-1301 USA
-//
-//===----------------------------------------------------------------------===//
-/// @file hlvm/AST/Conditionable.h
-/// @author Reid Spencer <reid at hlvm.org> (original author)
-/// @date 2006/05/04
-/// @since 0.1.0
-/// @brief Declares the class hlvm::AST::Conditionable
-//===----------------------------------------------------------------------===//
-
-#ifndef HLVM_AST_CONDITIONABLE_H
-#define HLVM_AST_CONDITIONABLE_H
-
-#include <hlvm/AST/Node.h>
-
-namespace hlvm
-{
-
-/// This class represents an HLVM Bundle. A Bundle is simply a collection of
-/// declarations and definitions. It is the root of the AST tree and also
-/// the grouping and namespace construct in HLVM. Every compilation unit is
-/// a Bundle. Bundles can also be nested in other Bundles. All programming
-/// constructs are defined as child nodes of some Bundle.
-/// @brief HLVM AST Bundle Node
-class Conditionable : public Node
-{
- /// @name Constructors
- /// @{
- public:
- Conditionable(
- NodeIDs id,
- Node* parent,
- const std::string& name,
- const std::string& condition_name)
- : Node(id,parent,name), cond_name_(condition_name) {}
- virtual ~Conditionable();
-
- /// @}
- /// @name Data
- /// @{
- protected:
- std::string cond_name_;
- /// @}
- friend class AST;
-};
-
-} // hlvm
-#endif
Modified: hlvm/trunk/hlvm/AST/Constant.h
URL: http://llvm.org/viewvc/llvm-project/hlvm/trunk/hlvm/AST/Constant.h?rev=38191&r1=38190&r2=38191&view=diff
==============================================================================
--- hlvm/trunk/hlvm/AST/Constant.h (original)
+++ hlvm/trunk/hlvm/AST/Constant.h Sat Jul 7 19:00:58 2007
@@ -36,14 +36,18 @@
{
/// This abstract base class represents a constant value in the HLVM Abstract
-/// Syntax Tree. All ConstantValues are immutable values of a specific type.
-/// ConstantValues do not have a storage location nor an address. However,
-/// as they are values they may be used as the operand of any instruction or
-/// in other places. ConstantValues are not suitable for linking. For that
-/// kind of constant you want the Constant class in Variable.h.
-/// There are many kinds of ConstantValues from simple literal values to
-/// complex constant expressions.
-/// @brief HLVM AST Constant Node
+/// Syntax Tree. All Constants are immutable values of a specific type.
+/// Constants do not have a storage location nor an address nor do they
+/// participate in linking. However, as they are values they may be used as
+/// the operand of instructions or as the initializers of variables. Constants
+/// do not participate in linking and are always internal to the bundle in which
+/// they appear. To create a linkable constant, declare a variable that is
+/// constant and initialize it with a Constant. There are many kinds of
+/// constants including simple literal values (numbers an text), complex
+/// constant expressions (constant computations), and aggregate constants that
+/// represent constant arrays, vectors, pointers and structures.
+/// @see hlvm/AST/Constants.h
+/// @brief AST Abstract Constant Node
class Constant : public Value
{
/// @name Constructors
Modified: hlvm/trunk/hlvm/AST/Constants.h
URL: http://llvm.org/viewvc/llvm-project/hlvm/trunk/hlvm/AST/Constants.h?rev=38191&r1=38190&r2=38191&view=diff
==============================================================================
--- hlvm/trunk/hlvm/AST/Constants.h (original)
+++ hlvm/trunk/hlvm/AST/Constants.h Sat Jul 7 19:00:58 2007
@@ -1,4 +1,4 @@
-//===-- AST Constant Expression Operators -----------------------*- C++ -*-===//
+//===-- AST Constant Values -------------------------------------*- C++ -*-===//
//
// High Level Virtual Machine (HLVM)
//
@@ -35,9 +35,11 @@
namespace hlvm
{
-/// This class represents an operator that yields a literal constant integer
-/// value.
-/// @brief HLVM AST Constant Integer Node
+/// This class provides an Abstract Syntax Tree node that yields a
+/// constant integer value. This kind of constant can represent integer valued
+/// constants of any of the signed or unsigned integer types of any bitsize.
+/// @see IntegerType
+/// @brief AST Constant Integer Node
class ConstantInteger: public Constant
{
/// @name Constructors
@@ -75,6 +77,11 @@
friend class AST;
};
+/// This class provides an Abstract Syntax Tree node that yields a constant
+/// real number value. This kind of constant can represent a constant real
+/// number value of any mantissa or exponent size.
+/// @see RealType
+/// @brief AST Constant Real Node
class ConstantReal : public Constant
{
/// @name Constructors
@@ -107,7 +114,15 @@
friend class AST;
};
-/// A constant textual string
+/// This class provides an Abstract Syntax Tree node that yields a constant
+/// text value. The constant value is encoded in UTF-8 but may be converted
+/// to other encodings depending on how it is used. For example, when used to
+/// initialize a TextType Variable that is using UTF-16 encoding, the conversion
+/// will occur whenever the Variable is loaded. UTF-8 encoding is used for
+/// constant text values to reduce storage requirements and for compatibility
+/// with older non-Unicode systems.
+/// @see TextType
+/// @brief AST Constant Text Node
class ConstantText : public Constant
{
/// @name Constructors
@@ -140,8 +155,13 @@
friend class AST;
};
-/// A zero initializer constant. It represents a constant of any type whose
-/// entire data is filled with zero bytes.
+/// This class provides an Abstract Syntax Tree node that yields a zero value
+/// for any type. In essence, this is a short-cut. Zero value constants are very
+/// common and defining them explicitly for each type of constant makes use of
+/// the AST constants cumbersome. The way to think about this node is that it
+/// represents a constant value of any type such that all the bits of that type
+/// are zero.
+/// AST Constant Zero Node
class ConstantZero : public Constant
{
/// @name Constructors
Modified: hlvm/trunk/hlvm/AST/ContainerType.h
URL: http://llvm.org/viewvc/llvm-project/hlvm/trunk/hlvm/AST/ContainerType.h?rev=38191&r1=38190&r2=38191&view=diff
==============================================================================
--- hlvm/trunk/hlvm/AST/ContainerType.h (original)
+++ hlvm/trunk/hlvm/AST/ContainerType.h Sat Jul 7 19:00:58 2007
@@ -35,8 +35,12 @@
namespace hlvm
{
-/// This class represents a Type that uses a single other element type in its
-/// construction.
+/// This class provides an Abstract Syntax Tree node that represents a uniform
+/// container type. Uniform container types are those types that reference
+/// another type. They may have multiple elements but all elements are of the
+/// same type, hence they are uniform. This is true of types such as AliasType
+/// (a simple renaming of another type), PointerType, ArrayType, and VectorTYpe.
+/// AST Abstract Uniform Container Type Node
class UniformContainerType : public Type
{
/// @name Constructors
@@ -75,8 +79,11 @@
/// @}
};
-/// This class represents a storage location that is a pointer to another
-/// type.
+/// This class provides an Abstract Syntax Tree node that represents a storage
+/// location that is a pointer to another storage location of a specific type.
+/// PointerType is a UniformContainerType meaning that the referrent object is
+/// of only one type.
+/// @brief AST Pointer Type Node
class PointerType : public UniformContainerType
{
/// @name Constructors
@@ -97,8 +104,18 @@
friend class AST;
};
-/// This class represents a resizeable, aligned array of some other type. The
-/// Array references a Type that specifies the type of elements in the array.
+/// This class provides an Abstract Syntax Tree note that represents an array of
+/// some type. An array is a sequential layout of multiple elements all of the
+/// same type. Arrays in HLVM are dynamically resizeable but the type
+/// specification can indicate a maximum size beyond which the array cannot
+/// grow. Setting the maximum size to 0 indicates that the size of the array
+/// is unbounded and it may grow to the limits of available memory. This
+/// usage is discouraged as knowing the maximum memory size can make the
+/// implementation of the array more efficient in its use of memory and limit
+/// the amount of reallocation necessary when the array changes size. An
+/// ArrayType is a UniformContainerType because it contains a number of elements
+/// all of uniform type.
+/// @brief AST Array Type Node
class ArrayType : public UniformContainerType
{
/// @name Constructors
@@ -134,10 +151,15 @@
friend class AST;
};
-/// This class represents a fixed size, packed vector of some other type.
-/// Where possible, HLVM will attempt to generate code that makes use of a
-/// machines vector instructions to process such types. If not possible, HLVM
-/// will treat the vector the same as an Array.
+/// This class provides an Abstract Syntax Tree Node that represents a fixed
+/// size, packed vector of some other type. Some languages call this an "array"
+/// but arrays in HLVM can be dynamically resized. Vectors, however, cannot
+/// be resized. Where possible, HLVM will attempt to generate code that makes
+/// use of a machines vector instructions to process vector types. Except for
+/// the fixed size, VectorType objects are identical in functionality to
+/// ArrayType objects. VectorType is a UniformContainerType because it
+/// represents a container of uniformly typed elements.
+/// @brief AST Vector Type Node
class VectorType : public UniformContainerType
{
/// @name Constructors
@@ -173,9 +195,19 @@
friend class AST;
};
-/// This class is type that combines a name with an arbitrary type. This
-/// construct is used any where a named and typed object is needed such as
-/// the parameter to a function or the field of a structure.
+/// This class provides an Abstract Syntax Tree node that is simply a renaming
+/// of another type. It adopts the characteristics of the referrent type. This
+/// construct is necessary in HLVM because type equivalence is done by name,
+/// not by semantics. To dissociate two types of equivalent semantics, say
+/// an integer type, one uses an AliasType to provide a new type name with the
+/// same semantics. AliasType is a UniformContainerType because it refers to
+/// another type of uniform type. AliasTypes are also used in the definition of
+/// a Function's formal arguments and a Structure's fields. In these situations
+/// the name provided by the AliasType forms the name of the argument or
+/// structure field.
+/// @see Function
+/// @see Structure
+/// @brief AST Alias Type Node
class AliasType : public UniformContainerType
{
/// @name Constructors
@@ -197,9 +229,12 @@
friend class AST;
};
-/// This class represents a Type in the HLVM Abstract Syntax Tree.
-/// A Type defines the format of storage.
-/// @brief HLVM AST Type Node
+/// This class provides an Abstract Syntax Tree node that represents a Type that
+/// contains elements of potentially disparate other types.
+/// @see ContinuationType
+/// @see StructureType
+/// @see SignatureType
+/// @brief AST Abstract Disparate Container Type Node
class DisparateContainerType : public Type
{
/// @name Types
@@ -256,11 +291,14 @@
/// @}
};
-
typedef AliasType Field;
-/// This class represents an HLVM type that is a sequence of data fields
-/// of varying type.
+/// This class provides an Abstract Syntax Tree node that represents an
+/// sequence type. A sequence type is a type that lays out its elements in
+/// sequential memory locations. Unlike ArrayType, SequenceType allows its
+/// elements to be of disparate type. Consequently, StructureType is a
+/// DisparateContainerType.
+/// @brief AST Structure Type Node
class StructureType : public DisparateContainerType
{
/// @name Constructors
@@ -293,7 +331,14 @@
friend class AST;
};
-/// This class holds data for a continuation. TBD later.
+/// This class provides an Abstract Syntax Tree node that represents data held
+/// for a continuation. A ContinutationType is a StructureType because it has
+/// the same semantics as a structure. It allows the programmer to store various
+/// bits of information that are to be restored at a later time, when the
+/// continuation is called. In addition, HLVM will (transparently) associate
+/// the runtime context for the continutation with the programmer's
+/// ContinuationType.
+/// @brief AST Continuation Type Node
class ContinuationType : public StructureType
{
/// @name Constructors
@@ -315,10 +360,16 @@
friend class AST;
};
+/// This typedef is used to just provide a more convenient name for AliasType
+/// when AliasType is being used as the Argument to a SignatureType.
+/// @brief AST Argument Type Node
typedef AliasType Argument;
-/// This class represents an HLVM type that is a sequence of data fields
+/// This class provides an Abstract Syntax Tree node that represents the call
+/// signature of an HLVM function. A SignatureType encapsulates the
/// of varying type.
+/// @see Function
+/// @brief AST Signature Type Node
class SignatureType : public DisparateContainerType
{
/// @name Constructors
More information about the llvm-commits
mailing list