[docs] Document usage of SmallVectorImpl in interfaces.
git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@177775 91177308-0d34-0410-b5e6-96231b3b80d8
diff --git a/docs/ProgrammersManual.rst b/docs/ProgrammersManual.rst
index 4fc4597..eed12e9 100644
--- a/docs/ProgrammersManual.rst
+++ b/docs/ProgrammersManual.rst
@@ -626,6 +626,33 @@
SmallVector also provides a nice portable and efficient replacement for
``alloca``.
+.. note::
+
+ Prefer to use ``SmallVectorImpl<T>`` in interfaces.
+
+ 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.
+
+ .. code-block:: c++
+
+ // BAD: Clients cannot pass e.g. SmallVector<Foo, 4>.
+ hardcodedSmallSize(SmallVector<Foo, 2> &Out);
+ // GOOD: Clients can pass any SmallVector<Foo, N>.
+ allowsAnySmallSize(SmallVectorImpl<Foo> &Out);
+
+ void someFunc() {
+ 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.
+
.. _dss_vector:
<vector>