Add and tidy doxygen comments and move implementation of toString() to newly

created CharUnits.cpp.

llvm-svn: 91719

3 files changed, 52 insertions, 14 deletions

diff --git a/clang/include/clang/AST/CharUnits.h b/clang/include/clang/AST/CharUnits.h
index 57d457f8920..c0290765b6e 100644
--- a/clang/include/clang/AST/CharUnits.h
+++ b/clang/include/clang/AST/CharUnits.h
@@ -14,13 +14,28 @@
 #ifndef LLVM_CLANG_AST_CHARUNITS_H
 #define LLVM_CLANG_AST_CHARUNITS_H
 
-#include "llvm/ADT/StringExtras.h"
 #include "llvm/System/DataTypes.h"
 
 #include <string>
 
 namespace clang {
-  // An opaque type for sizes expressed in character units 
+  
+  /// CharUnits - This is an opaque type for sizes expressed in character units.
+  /// Instances of this type represent a quantity as a multiple of the size 
+  /// of the standard C type, char, on the target architecture. As an opaque
+  /// type, CharUnits protects you from accidentally combining operations on
+  /// quantities in bit units and character units. 
+  ///
+  /// It should be noted that characters and bytes are distinct concepts. Bytes
+  /// refer to addressable units of data storage on the target machine, and
+  /// characters are members of a set of elements used for the organization,
+  /// control, or representation of data. According to C99, bytes are allowed
+  /// to exceed characters in size, although currently, clang only supports
+  /// architectures where the two are the same size.
+  /// 
+  /// For portability, never assume that a target character is 8 bits wide. Use 
+  /// CharUnit values whereever you calculate sizes, offsets, or alignments
+  /// in character units.
   class CharUnits {
     public:
       typedef int64_t RawType;
@@ -32,15 +47,15 @@ namespace clang {
 
     public:
 
-      /// A default constructor
+      /// CharUnits - A default constructor.
       CharUnits() : Quantity(0) {}
 
-      /// Zero - Construct a CharUnits quantity of zero
+      /// Zero - Construct a CharUnits quantity of zero.
       static CharUnits Zero() {
         return CharUnits(0);
       }
 
-      /// One - Construct a CharUnits quantity of one
+      /// One - Construct a CharUnits quantity of one.
       static CharUnits One() {
         return CharUnits(1);
       }
@@ -50,7 +65,7 @@ namespace clang {
         return CharUnits(Quantity); 
       }
 
-      // compound assignment
+      // Compound assignment.
       CharUnits& operator+= (const CharUnits &Other) {
         Quantity += Other.Quantity;
         return *this;
@@ -60,7 +75,7 @@ namespace clang {
         return *this;
       }
        
-      // comparison operators
+      // Comparison operators.
       bool operator== (const CharUnits &Other) const {
         return Quantity == Other.Quantity;
       }
@@ -68,7 +83,7 @@ namespace clang {
         return Quantity != Other.Quantity;
       }
 
-      // relational operators
+      // Relational operators.
       bool operator<  (const CharUnits &Other) const { 
         return Quantity <  Other.Quantity; 
       }
@@ -82,7 +97,7 @@ namespace clang {
         return Quantity >= Other.Quantity; 
       }
 
-      // other predicates
+      // Other predicates.
       
       /// isZero - Test whether the quantity equals zero.
       bool isZero() const     { return Quantity == 0; }
@@ -96,7 +111,7 @@ namespace clang {
       /// isNegative - Test whether the quantity is less than zero.
       bool isNegative() const { return Quantity  < 0; }
 
-      // arithmetic operators
+      // Arithmetic operators.
       CharUnits operator* (RawType N) const {
         return CharUnits(Quantity * N);
       }
@@ -119,12 +134,10 @@ namespace clang {
         return CharUnits(Quantity - Other.Quantity);
       }
       
-      // conversions
+      // Conversions.
 
       /// toString - Convert to a string.
-      std::string toString() const {
-        return llvm::itostr(Quantity);
-      }
+      std::string toString() const;
 
       /// getRaw - Get the raw integer representation of this quantity.
       RawType getRaw() const { return Quantity; }
diff --git a/clang/lib/AST/CMakeLists.txt b/clang/lib/AST/CMakeLists.txt
index 5aecf878c92..98880b5f77d 100644
--- a/clang/lib/AST/CMakeLists.txt
+++ b/clang/lib/AST/CMakeLists.txt
@@ -5,6 +5,7 @@ add_clang_library(clangAST
   ASTConsumer.cpp
   ASTContext.cpp
   CXXInheritance.cpp
+  CharUnits.cpp
   Decl.cpp
   DeclBase.cpp
   DeclCXX.cpp
diff --git a/clang/lib/AST/CharUnits.cpp b/clang/lib/AST/CharUnits.cpp
new file mode 100644
index 00000000000..4886cffbbcc
--- /dev/null
+++ b/clang/lib/AST/CharUnits.cpp
@@ -0,0 +1,24 @@
+//===--- CharUnits.cpp - Character units for sizes and offsets ------------===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+//
+//  This file implements the CharUnits class.
+//
+//===----------------------------------------------------------------------===//
+
+#include "clang/AST/CharUnits.h"
+
+#include "llvm/ADT/StringExtras.h"
+
+#include <string>
+
+using namespace clang;
+
+std::string CharUnits::toString() const {
+  return llvm::itostr(Quantity);
+}