For PR778:

Move file-scoped documentation to class-scoped so it is more readily
accessible.


git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@28689 91177308-0d34-0410-b5e6-96231b3b80d8

include/llvm/AbstractTypeUser.h

@@ -7,21 +7,7 @@
 //
 //===----------------------------------------------------------------------===//
 //
-// The AbstractTypeUser class is an interface to be implemented by classes who
+// This file declares the AbstractTypeUser class.
-// could possible use an abstract type.  Abstract types are denoted by the
-// isAbstract flag set to true in the Type class.  These are classes that
-// contain an Opaque type in their structure somehow.
-//
-// Classes must implement this interface so that they may be notified when an
-// abstract type is resolved.  Abstract types may be resolved into more concrete
-// types through: linking, parsing, and bytecode reading.  When this happens,
-// all of the users of the type must be updated to reference the new, more
-// concrete type.  They are notified through the AbstractTypeUser interface.
-//
-// In addition to this, AbstractTypeUsers must keep the use list of the
-// potentially abstract type that they reference up-to-date.  To do this in a
-// nice, transparent way, the PATypeHandle class is used to hold "Potentially
-// Abstract Types", and keep the use list of the abstract types up-to-date.
 //
 //===----------------------------------------------------------------------===//
 
@@ -42,6 +28,23 @@ namespace llvm {
 class Type;
 class DerivedType;
 
+/// The AbstractTypeUser class is an interface to be implemented by classes who
+/// could possibly use an abstract type.  Abstract types are denoted by the
+/// isAbstract flag set to true in the Type class.  These are classes that
+/// contain an Opaque type in their structure somewhere.
+///
+/// Classes must implement this interface so that they may be notified when an
+/// abstract type is resolved.  Abstract types may be resolved into more 
+/// concrete types through: linking, parsing, and bytecode reading.  When this 
+/// happens, all of the users of the type must be updated to reference the new,
+/// more concrete type.  They are notified through the AbstractTypeUser 
+/// interface.
+///
+/// In addition to this, AbstractTypeUsers must keep the use list of the
+/// potentially abstract type that they reference up-to-date.  To do this in a
+/// nice, transparent way, the PATypeHandle class is used to hold "Potentially
+/// Abstract Types", and keep the use list of the abstract types up-to-date.
+/// @brief LLVM Abstract Type User Representation
 class AbstractTypeUser {
 protected:
   virtual ~AbstractTypeUser();                        // Derive from me

include/llvm/Argument.h

@@ -7,8 +7,7 @@
 //
 //===----------------------------------------------------------------------===//
 //
-// This file defines the Argument class, which represents an incoming formal
+// This file declares the Argument class. 
-// argument to a Function.
 //
 //===----------------------------------------------------------------------===//
 
@@ -23,6 +22,11 @@ template<typename SC> struct ilist_traits;
 template<typename ValueSubClass, typename ItemParentClass, typename SymTabClass,
          typename SubClass> class SymbolTableListTraits;
 
+/// A class to represent an incoming formal argument to a Function. An argument
+/// is a very simple Value. It is essentially a named (optional) type. When used
+/// in the body of a function, it represents the value of the actual argument
+/// the function was called with.
+/// @brief LLVM Argument representation  
 class Argument : public Value {  // Defined in the Function.cpp file
   Function *Parent;
 

include/llvm/BasicBlock.h

@@ -8,21 +8,7 @@
 //===----------------------------------------------------------------------===//
 //
 //
-// This file contains the declaration of the BasicBlock class, which represents
+// This file contains the declaration of the BasicBlock class.
-// a single basic block in the VM.
-//
-// Note that basic blocks themselves are Value's, because they are referenced
-// by instructions like branches and can go in switch tables and stuff...
-//
-///===---------------------------------------------------------------------===//
-//
-// Note that well formed basic blocks are formed of a list of instructions
-// followed by a single TerminatorInst instruction.  TerminatorInst's may not
-// occur in the middle of basic blocks, and must terminate the blocks.
-//
-// This code allows malformed basic blocks to occur, because it may be useful
-// in the intermediate stage modification to a program.
-//
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_BASICBLOCK_H
@@ -46,6 +32,20 @@ template<> struct ilist_traits<Instruction>
   static iplist<Instruction> &getList(BasicBlock *BB);
 };
 
+/// This represents a single basic block in LLVM. A basic block is simply a
+/// container of instructions that execute sequentially. Basic blocks are Values
+/// because they are referenced by instructions such as branches and switch
+/// tables. The type of a BasicBlock is "Type::LabelTy" because the basic block
+/// represents a label to which a branch can jump.
+///
+/// A well formed basic block is formed of a list of non-terminating 
+/// instructions followed by a single TerminatorInst instruction.  
+/// TerminatorInst's may not occur in the middle of basic blocks, and must 
+/// terminate the blocks. The BasicBlock class allows malformed basic blocks to
+/// occur because it may be useful in the intermediate stage of constructing or
+/// modifying a program. However, the verifier will ensure that basic blocks
+/// are "well formed".
+/// @brief LLVM Basic Block Representation
 class BasicBlock : public Value {       // Basic blocks are data objects also
 public:
   typedef iplist<Instruction> InstListType;

include/llvm/CallingConv.h

@@ -7,8 +7,7 @@
 //
 //===----------------------------------------------------------------------===//
 //
-// This file defines a set of enums which specify the assigned numeric values
+// This file defines LLVM's set of calling conventions. 
-// for known llvm calling conventions.
 //
 //===----------------------------------------------------------------------===//
 
@@ -21,6 +20,9 @@ namespace llvm {
 /// the well-known calling conventions.
 ///
 namespace CallingConv {
+  /// A set of enums which specify the assigned numeric values for known llvm 
+  /// calling conventions.
+  /// @brief LLVM Calling Convention Representation
   enum ID {
     // C - The default llvm calling convention, compatible with C.  This
     // convention is the only calling convention that supports varargs calls.

include/llvm/Constant.h

@@ -18,6 +18,23 @@
 
 namespace llvm {
 
+/// This is an important base class in LLVM. It provides the common facilities
+/// of all constant values in an LLVM program. A constant is a value that is
+/// immutable at runtime. Functions are constants because their address is
+/// immutable. Same with global variables. 
+/// 
+/// All constants share the capabilities provided in this class. All constants
+/// can have a null value. They can have an operand list. Constants can be
+/// simple (integer and floating point values), complex (arrays and structures),
+/// or expression based (computations yielding a constant value composed of 
+/// only certain operators and other constant values).
+/// 
+/// Note that Constants are immutable (once created they never change) 
+/// and are fully shared by structural equivalence.  This means that two 
+/// structurally equivalent constants will always have the same address.  
+/// Constant's are created on demand as needed and never deleted: thus clients 
+/// don't have to worry about the lifetime of the objects.
+/// @brief LLVM Constant Representation
 class Constant : public User {
   void operator=(const Constant &);     // Do not implement
   Constant(const Constant &);           // Do not implement

include/llvm/Value.h

@@ -7,9 +7,7 @@
 //
 //===----------------------------------------------------------------------===//
 //
-// This file defines the very important Value class.  This is subclassed by a
+// This file declares the Value class. 
-// bunch of other important classes, like Instruction, Function, Type, etc...
-//
 // This file also defines the Use<> template for users of value.
 //
 //===----------------------------------------------------------------------===//
@@ -38,9 +36,16 @@ class SymbolTable;
 //                                 Value Class
 //===----------------------------------------------------------------------===//
 
-/// Value - The base class of all values computed by a program that may be used
+/// This is a very important LLVM class. It is the base class of all values 
-/// as operands to other values.
+/// computed by a program that may be used as operands to other values. Value is
+/// the super class of other important classes such as Instruction and Function.
+/// All Values have a Type. Type is not a subclass of Value. All types can have
+/// a name and they should belong to some Module. Setting the name on the Value
+/// automatically update's the module's symbol table.
 ///
+/// Every value has a "use list" that keeps track of which other Values are
+/// using this Value.
+/// @brief LLVM Value Representation
 class Value {
   unsigned short SubclassID;         // Subclass identifier (for isa/dyn_cast)
 protected:
@@ -133,13 +138,10 @@ public:
   ///
   void addUse(Use &U) { U.addToList(&UseList); }
 
-  /// getValueType - Return an ID for the concrete type of this object.  This is
+  /// An enumeration for keeping track of the concrete subclass of Value that
-  /// used to implement the classof checks.  This should not be used for any
+  /// is actually instantiated. Values of this enumeration are kept in the 
-  /// other purpose, as the values may change as LLVM evolves.  Also, note that
+  /// Value classes SubclassID field. They are used for concrete type
-  /// starting with the InstructionVal value, the value stored is actually the
+  /// identification.
-  /// Instruction opcode, so there are more than just these values possible here
-  /// (and Instruction must be last).
-  ///
   enum ValueTy {
     ArgumentVal,              // This is an instance of Argument
     BasicBlockVal,            // This is an instance of BasicBlock
@@ -163,6 +165,14 @@ public:
     ConstantFirstVal = FunctionVal,
     ConstantLastVal  = ConstantPointerNullVal
   };
+
+  /// getValueType - Return an ID for the concrete type of this object.  This is
+  /// used to implement the classof checks.  This should not be used for any
+  /// other purpose, as the values may change as LLVM evolves.  Also, note that
+  /// starting with the InstructionVal value, the value stored is actually the
+  /// Instruction opcode, so there are more than just these values possible here
+  /// (and Instruction must be last).
+  ///
   unsigned getValueType() const {
     return SubclassID;
   }