docs: Emphasize ArrayRef over SmallVectorImpl

[dexonsmith]

Summary

The section on SmallVector has a note about preferring SmallVectorImpl for APIs but doesn't mention ArrayRef. Although ArrayRef is discussed elsewhere, let's re-emphasize here.

[dberris]

Drive-by-review here.

llvm/docs/ProgrammersManual.rst

1550

s/basically just//

1577–1580

I suggest "discouraged" instead of "bad".

1588–1589

s/is so widely/is widely/
s/really isn't/is no longer/
s/"private to the implementation" anymore/an implementation detail/

[bogner]

LGTM once dberris's suggestions are taken into account

llvm/docs/ProgrammersManual.rst

#. Many LLVM APIs take a SmallVectorImpl as an out parameter (see the note
    below).
 
 #. SmallVector with N equal to 0 is smaller than std::vector on 64-bit
    platforms, since it uses ``unsigned`` (instead of ``void*``) for its size
    and capacity.
 
 .. note::
 
-   Prefer to use ``SmallVectorImpl<T>`` as a parameter type.
+   Prefer to use ``ArrayRef<T>`` or ``SmallVectorImpl<T>`` as a parameter type.
 
-   In APIs that don't care about the "small size" (most?), prefer to use
-   the ``SmallVectorImpl<T>`` class, which is basically just the "vector
-   header" (and methods) without the elements allocated after it. Note that
-   ``SmallVector<T, N>`` inherits from ``SmallVectorImpl<T>`` so the
-   conversion is implicit and costs nothing. E.g.
+   It's rarely appropriate to use ``SmallVector<T, N>`` as a parameter type.
+   If an API only reads from the vector, it should use :ref:`ArrayRef
+   <dss_arrayref>`.  Even if an API updates the vector the "small size" is
+   unlikely to be relevant; such an API should use the ``SmallVectorImpl<T>``
+   class, which is the "vector header" (and methods) without the elements
+   allocated after it. Note that ``SmallVector<T, N>`` inherits from
+   ``SmallVectorImpl<T>`` so the conversion is implicit and costs nothing. E.g.
 
    .. code-block:: c++
 
-      // BAD: Clients cannot pass e.g. SmallVector<Foo, 4>.
+      // DISCOURAGED: Clients cannot pass e.g. raw arrays.
+      hardcodedContiguousStorage(const SmallVectorImpl<Foo> &In);
+      // ENCOURAGED: Clients can pass any contiguous storage of Foo.
+      allowsAnyContiguousStorage(ArrayRef<Foo> In);
+
+      void someFunc1() {
+        Foo Vec[] = { /* ... */ };
+        hardcodedContiguousStorage(Vec); // Error.
+        allowsAnyContiguousStorage(Vec); // Works.
+      }
+
+      // DISCOURAGED: Clients cannot pass e.g. SmallVector<Foo, 8>.
       hardcodedSmallSize(SmallVector<Foo, 2> &Out);
-      // GOOD: Clients can pass any SmallVector<Foo, N>.
+      // ENCOURAGED: Clients can pass any SmallVector<Foo, N>.
       allowsAnySmallSize(SmallVectorImpl<Foo> &Out);
 
-      void someFunc() {
+      void someFunc2() {
         SmallVector<Foo, 8> Vec;
         hardcodedSmallSize(Vec); // Error.
         allowsAnySmallSize(Vec); // Works.
       }
 
-   Even though it has "``Impl``" in the name, this is so widely used that
-   it really isn't "private to the implementation" anymore. A name like
-   ``SmallVectorHeader`` would be more appropriate.
+   Even though it has "``Impl``" in the name, SmallVectorImpl is widely used
+   and is no longer "private to the implementation". A name like
+   ``SmallVectorHeader`` might be more appropriate.
 
 .. _dss_vector:
 
 <vector>
 ^^^^^^^^
 
 ``std::vector<T>`` is well loved and respected.  However, ``SmallVector<T, 0>``
 is often a better option due to the advantages listed above.  std::vector is
 still useful when you need to store more than ``UINT32_MAX`` elements or when
 interfacing with code that expects vectors :).
 
 One worthwhile note about std::vector: avoid code like this:
 
 .. code-block:: c++
 
   for ( ... ) {
      std::vector<foo> V;