[SmallVector] Copy new docs into Doxygen comment

[scott.linder]

Summary

I went to find a reference for the new recommended behavior in the
sources, and ended up had to refer to D92522 to determine where it ended
up (i.e. ProgrammersManual.rst).

At the risk of the two copies diverging, it seemed useful to note the
new recommended use of SmallVector directly at the class declaration,
and also get the benefit of it appearing in a slightly emphasized way in
the rendered Doxygen.

[scott.linder]

Small proposed addition to try to encourage the migration to the no-explicit-N form, let me know what you think.

[lattner]

nice, thank you!

[silvas]

Thanks!

You might want to link to the ProgrammersManual directly from here as well.

[scott.linder]

In D93069#2447155, @silvas wrote:

Thanks!

You might want to link to the ProgrammersManual directly from here as well.

Woops, sorry for not adding you originally! I think I just copied the reviewers verbatim and didn't think about the author...

I added a "see also" link in 32910f780df4f5add290f176459648f2326674f5, let me know if it isn't what you had in mind. Cheers!

llvm/include/llvm/ADT/SmallVector.h

 };
 
 /// This is a 'vector' (really, a variable-sized array), optimized
 /// for the case when the array is small.  It contains some number of elements
 /// in-place, which allows it to avoid heap allocation when the actual number of
 /// elements is below that threshold.  This allows normal "small" cases to be
 /// fast without losing generality for large inputs.
 ///
-/// Note that this does not attempt to be exception safe.
+/// \note
+/// In the absence of a well-motivated choice for the number of inlined
+/// elements \p N, it is recommended to use \c SmallVector<T> (that is,
+/// omitting the \p N). This will choose a default number of inlined elements
+/// reasonable for allocation on the stack (for example, trying to keep \c
+/// sizeof(SmallVector<T>) around 64 bytes).
+///
+/// \warning This does not attempt to be exception safe.
 ///
 template <typename T,
           unsigned N = CalculateSmallVectorDefaultInlinedElements<T>::value>
 class LLVM_GSL_OWNER SmallVector : public SmallVectorImpl<T>,
                                    SmallVectorStorage<T, N> {
 public:
   SmallVector() : SmallVectorImpl<T>(N) {}