WTF: Update comments for Vector.

third_party/WebKit/Source/wtf/Vector.h

 /*
  *  Copyright (C) 2005, 2006, 2007, 2008 Apple Inc. All rights reserved.
  *
  *  This library is free software; you can redistribute it and/or
  *  modify it under the terms of the GNU Library General Public
  *  License as published by the Free Software Foundation; either
  *  version 2 of the License, or (at your option) any later version.
  *
  *  This library is distributed in the hope that it will be useful,
  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
@@ skipping 39 matching lines @@
 #else
 #ifndef WTF_VECTOR_INITIAL_SIZE
 #define WTF_VECTOR_INITIAL_SIZE 4
 #endif
 static const size_t kInitialVectorSize = WTF_VECTOR_INITIAL_SIZE;
 #endif
 
 template <typename T, size_t inlineBuffer, typename Allocator>
 class Deque;
 
+//
+// Vector Traits
+//
+
+// Bunch of traits for Vector are defined here, with which you can customize
+// Vector's behavior. In most cases the default traits are appropriate, so you
+// usually don't have to specialize those traits by yourself.
+
 template <bool needsDestruction, typename T>
 struct VectorDestructor;
 
 template <typename T>
 struct VectorDestructor<false, T> {
   STATIC_ONLY(VectorDestructor);
   static void destruct(T*, T*) {}
 };
 
 template <typename T>
@@ skipping 202 matching lines @@
 
 template <typename T>
 struct VectorElementComparer<std::unique_ptr<T>> {
   STATIC_ONLY(VectorElementComparer);
   template <typename U>
   static bool compareElement(const std::unique_ptr<T>& left, const U& right) {
     return left.get() == right;
   }
 };
 
+// A collection of all the traits used by Vector. This is basically an
+// implementation detail of Vector, and you should specialize individual traits
+// defined above, if you want to customize Vector's behavior.
 template <typename T>
 struct VectorTypeOperations {
   STATIC_ONLY(VectorTypeOperations);
   static void destruct(T* begin, T* end) {
     VectorDestructor<VectorTraits<T>::needsDestruction, T>::destruct(begin,
                                                                      end);
   }
 
   static void initialize(T* begin, T* end) {
     VectorInitializer<VectorTraits<T>::canInitializeWithMemset, T>::initialize(
@@ skipping 28 matching lines @@
         a, b, size);
   }
 
   template <typename U>
   static bool compareElement(const T& left, U&& right) {
     return VectorElementComparer<T>::compareElement(left,
                                                     std::forward<U>(right));
   }
 };
 
+//
+// VectorBuffer
+//
+
+// VectorBuffer is an implementation detail of Vector and Deque. It manages
+// Vector's underlying buffer, and does operations like allocation or
+// expansion.
+//
+// Not meant for general consumption.
+
 template <typename T, bool hasInlineCapacity, typename Allocator>
 class VectorBufferBase {
   WTF_MAKE_NONCOPYABLE(VectorBufferBase);
   DISALLOW_NEW();
 
  public:
   void allocateBuffer(size_t newCapacity) {
     DCHECK(newCapacity);
     DCHECK_LE(newCapacity,
               Allocator::template maxElementCountInBackingStore<T>());
@@ skipping 448 matching lines @@
   static const size_t m_inlineBufferSize = inlineCapacity * sizeof(T);
   T* inlineBuffer() { return reinterpret_cast_ptr<T*>(m_inlineBuffer.buffer); }
   const T* inlineBuffer() const {
     return reinterpret_cast_ptr<const T*>(m_inlineBuffer.buffer);
   }
 
   AlignedBuffer<m_inlineBufferSize, WTF_ALIGN_OF(T)> m_inlineBuffer;
   template <typename U, size_t inlineBuffer, typename V>
   friend class Deque;
 };
-// Heap-allocated vectors with no inlineCapacity never need a destructor.
+
+//
+// Vector
+//
+
 template <typename T,
           size_t inlineCapacity = 0,
           typename Allocator = PartitionAllocator>
 class Vector
     : private VectorBuffer<T, INLINE_CAPACITY, Allocator>,
+      // Heap-allocated vectors with no inlineCapacity never need a destructor.
       public ConditionalDestructor<Vector<T, INLINE_CAPACITY, Allocator>,
                                    (INLINE_CAPACITY == 0) &&
                                        Allocator::isGarbageCollected> {
   USE_ALLOCATOR(Vector, Allocator);
   using Base = VectorBuffer<T, INLINE_CAPACITY, Allocator>;
   using TypeOperations = VectorTypeOperations<T>;
   using OffsetRange = typename Base::OffsetRange;
 
  public:
   typedef T ValueType;
@@ skipping 219 matching lines @@
   template <typename U>
   void appendSlowCase(U&&);
 
   using Base::m_size;
   using Base::buffer;
   using Base::swapVectorBuffer;
   using Base::allocateBuffer;
   using Base::allocationSize;
 };
 
+//
+// Vector out-of-line implementation
+//
+
 template <typename T, size_t inlineCapacity, typename Allocator>
 Vector<T, inlineCapacity, Allocator>::Vector(const Vector& other)
     : Base(other.capacity()) {
   ANNOTATE_NEW_BUFFER(begin(), capacity(), other.size());
   m_size = other.size();
   TypeOperations::uninitializedCopy(other.begin(), other.end(), begin());
 }
 
 template <typename T, size_t inlineCapacity, typename Allocator>
 template <size_t otherCapacity>
@@ skipping 566 matching lines @@
           visitor, *const_cast<T*>(bufferEntry));
     checkUnusedSlots(buffer() + size(), buffer() + capacity());
   }
 }
 
 }  // namespace WTF
 
 using WTF::Vector;
 
 #endif  // WTF_Vector_h