Add a comment explaining how base::LinkedList differs from std::list, to help...

base/linked_list.h

 // Copyright (c) 2009 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef BASE_LINKED_LIST_H_
 #define BASE_LINKED_LIST_H_
 
-// Simple LinkedList type.
+// Simple LinkedList type. (See the Q&A section to understand how this
+// differs from std::list).
 //
 // To use, start by declaring the class which will be contained in the linked
 // list, as extending LinkNode (this gives it next/previous pointers).
 //
 //   class MyNodeType : public LinkNode<MyNodeType> {
 //     ...
 //   };
 //
 // Next, to keep track of the list's head/tail, use a LinkedList instance:
 //
@@ skipping 21 matching lines @@
 //
 // Or to iterate the linked list backwards:
 //
 //   for (LinkNode<MyNodeType>* node = list.tail();
 //        node != list.end();
 //        node = node->previous()) {
 //     MyNodeType* value = node->value();
 //     ...
 //   }
 //
+// Questions and Answers:
+//
+// Q. Should I use std::list or base::LinkedList?
+//
+// A. The main reason to use base::LinkedList over std::list is
+//    performance. If you don't care about the performance differences
+//    then use an STL container, as it makes for better code readability.
+//
+//    Comparing the performance of base::LinkedList<T> to std::list<T*>:
+//
+//    * Erasing an element of type T* from base::LinkedList<T> is
+//      an O(1) operation. Whereas for std::list<T*> it is O(n).
+//      That is because with std::list<T*> you must obtain an
+//      iterator to the T* element before you can call erase(iterator).
+//
+//    * Insertion operations with base::LinkedList<T> never require
+//      heap allocations.
+//
+// Q. How does base::LinkedList implementation differ from std::list?
+//
+// A. Doubly-linked lists are made up of nodes that contain "next" and
+//    "previous" pointers that reference other nodes in the list.
+//
+//    With base::LinkedList<T>, the type being inserted already reserves
+//    space for the "next" and "previous" pointers (base::LinkNode<T>*).
+//    Whereas with std::list<T> the type can be anything, so the implementation
+//    needs to glue on the "next" and "previous" pointers using
+//    some internal node type.
 
 namespace base {
 
 template <typename T>
 class LinkNode {
  public:
   LinkNode() : previous_(0), next_(0) {}
   LinkNode(LinkNode<T>* previous, LinkNode<T>* next)
       : previous_(previous), next_(next) {}
 
@@ skipping 66 matching lines @@
     return &root_;
   }
 
  private:
   LinkNode<T> root_;
 };
 
 }  // namespace base
 
 #endif  // BASE_LINKED_LIST_H_