Don't duplicate name in comments. NFC.

llvm-svn: 221762

llvm/include/llvm/Support/MemoryObject.h

@@ -14,29 +14,25 @@
 
 namespace llvm {
 
-/// MemoryObject - Abstract base class for contiguous addressable memory.
+/// Abstract base class for contiguous addressable memory. Necessary for cases
-///   Necessary for cases in which the memory is in another process, in a
+/// in which the memory is in another process, in a file, or on a remote
-///   file, or on a remote machine.
+/// machine. All size and offset parameters are uint64_ts, to allow 32-bit
-///   All size and offset parameters are uint64_ts, to allow 32-bit processes
+/// processes access to 64-bit address spaces.
-///   access to 64-bit address spaces.
 class MemoryObject {
 public:
-  /// Destructor      - Override as necessary.
   virtual ~MemoryObject();
 
-  /// getExtent       - Returns the size of the region in bytes.  (The region is
+  /// Returns the size of the region in bytes.  (The region is contiguous, so
-  ///                   contiguous, so the highest valid address of the region
+  /// the highest valid address of the region is getExtent() - 1).
-  ///                   is getBase() + getExtent() - 1).
   ///
   /// @result         - The size of the region.
   virtual uint64_t getExtent() const = 0;
 
-  /// readBytes       - Tries to read a contiguous range of bytes from the
+  /// Tries to read a contiguous range of bytes from the region, up to the end
-  ///                   region, up to the end of the region.
+  /// of the region. You should override this function if there is a quicker way
-  ///                   You should override this function if there is a quicker
+  /// than going back and forth with individual bytes.
-  ///                   way than going back and forth with individual bytes.
   ///
-  /// @param address  - The address of the first byte, in the same space as 
+  /// @param address  - The address of the first byte, in the same space as
   ///                   getBase().
   /// @param size     - The number of bytes to copy.
   /// @param buf      - A pointer to a buffer to be filled in.  Must be non-NULL

llvm/include/llvm/Support/StreamableMemoryObject.h

@@ -21,50 +21,47 @@
 
 namespace llvm {
 
-/// StreamableMemoryObject - Interface to data which might be streamed.
+/// Interface to data which might be streamed. Streamability has 2 important
-/// Streamability has 2 important implications/restrictions. First, the data
+/// implications/restrictions. First, the data might not yet exist in memory
-/// might not yet exist in memory when the request is made. This just means
+/// when the request is made. This just means that readByte/readBytes might have
-/// that readByte/readBytes might have to block or do some work to get it.
+/// to block or do some work to get it. More significantly, the exact size of
-/// More significantly, the exact size of the object might not be known until
+/// the object might not be known until it has all been fetched. This means that
-/// it has all been fetched. This means that to return the right result,
+/// to return the right result, getExtent must also wait for all the data to
-/// getExtent must also wait for all the data to arrive; therefore it should
+/// arrive; therefore it should not be called on objects which are actually
-/// not be called on objects which are actually streamed (this would defeat
+/// streamed (this would defeat the purpose of streaming). Instead,
-/// the purpose of streaming). Instead, isValidAddress and isObjectEnd can be
+/// isValidAddress and isObjectEnd can be used to test addresses without knowing
-/// used to test addresses without knowing the exact size of the stream.
+/// the exact size of the stream. Finally, getPointer can be used instead of
-/// Finally, getPointer can be used instead of readBytes to avoid extra copying.
+/// readBytes to avoid extra copying.
 class StreamableMemoryObject : public MemoryObject {
  public:
-  /// Destructor      - Override as necessary.
   virtual ~StreamableMemoryObject();
 
-  /// getPointer  - Ensures that the requested data is in memory, and returns
+  /// Ensures that the requested data is in memory, and returns a pointer to it.
-  ///               A pointer to it. More efficient than using readBytes if the
+  /// More efficient than using readBytes if the data is already in memory. May
-  ///               data is already in memory.
+  /// block until (address - base + size) bytes have been read
-  ///               May block until (address - base + size) bytes have been read
   /// @param address - address of the byte, in the same space as getBase()
   /// @param size    - amount of data that must be available on return
   /// @result        - valid pointer to the requested data
   virtual const uint8_t *getPointer(uint64_t address, uint64_t size) const = 0;
 
-  /// isValidAddress - Returns true if the address is within the object
+  /// Returns true if the address is within the object (i.e. between base and
-  ///                  (i.e. between base and base + extent - 1 inclusive)
+  /// base + extent - 1 inclusive). May block until (address - base) bytes have
-  ///                  May block until (address - base) bytes have been read
+  /// been read
   /// @param address - address of the byte, in the same space as getBase()
   /// @result        - true if the address may be read with readByte()
   virtual bool isValidAddress(uint64_t address) const = 0;
 
-  /// isObjectEnd    - Returns true if the address is one past the end of the
+  /// Returns true if the address is one past the end of the object (i.e. if it
-  ///                  object (i.e. if it is equal to base + extent)
+  /// is equal to base + extent). May block until (address - base) bytes have
-  ///                  May block until (address - base) bytes have been read
+  /// been read
   /// @param address - address of the byte, in the same space as getBase()
   /// @result        - true if the address is equal to base + extent
   virtual bool isObjectEnd(uint64_t address) const = 0;
 };
 
-/// StreamingMemoryObject - interface to data which is actually streamed from
+/// Interface to data which is actually streamed from a DataStreamer. In
-/// a DataStreamer. In addition to inherited members, it has the
+/// addition to inherited members, it has the dropLeadingBytes and
-/// dropLeadingBytes and setKnownObjectSize methods which are not applicable
+/// setKnownObjectSize methods which are not applicable to non-streamed objects.
-/// to non-streamed objects.
 class StreamingMemoryObject : public StreamableMemoryObject {
 public:
   StreamingMemoryObject(DataStreamer *streamer);