Add better documentation for iterator facade subclasses.

[chandlerc]

llvm/include/llvm/ADT/iterator.h

45–49

For both forward and bidirectional, you can instead implement (one overload of) operator++ and operator-- respectively. Generally, that's a better option for such iterators.

For random-access, you can skip implementing those because we can generate them from the += and -= (which we have to have you implement in order for random access to be fast).

[chandlerc]

Awesome, thanks for making this more clear!

[zturner]

This was submitted a while ago.

llvm/include/llvm/ADT/iterator.h

 /// subtraction in terms of addition by negating the difference. Negation isn't
 /// always information preserving, and I can see very reasonable iterator
 /// designs where this doesn't work well. It doesn't really force much added
 /// boilerplate anyways.
 ///
 /// Another abstraction that this doesn't provide is implementing increment in
 /// terms of addition of one. These aren't equivalent for all iterator
 /// categories, and respecting that adds a lot of complexity for little gain.
+///
+/// Classes wishing to use `iterator_facade_base` should implement the following
+/// methods:
+///
+/// Forward Iterators:
+///   DerivedT &operator=(const DerivedT &R);
+///   bool operator==(const DerivedT &R) const;
+///   const T &operator*() const;
+///   T &operator*();
+///   DerivedT &operator+=(DifferenceTypeT N);
+///
+/// Bidirectional Iterators:
+///   (All methods of forward iterators, plus the following)
+///   DerivedT &operator-=(DifferenceTypeT N);
+///
+/// Random-access Iterators:
+///   (All methods of bidirectional iterators, plus the following)
+///   bool operator<(const DerivedT &RHS) const;
+///   DifferenceTypeT operator-(const DerivedT &R) const;
+///
 template <typename DerivedT, typename IteratorCategoryT, typename T,
           typename DifferenceTypeT = std::ptrdiff_t, typename PointerT = T *,
           typename ReferenceT = T &>
 class iterator_facade_base
     : public std::iterator<IteratorCategoryT, T, DifferenceTypeT, PointerT,
                            ReferenceT> {
 protected:
   enum {