Add std_auto_ptr.i defining typemaps for returning std::auto_ptr<>.

These typemaps are currently defined for C#, Java and Python only and the
tests are provided only for these languages.

Also add a brief description of the new header to the documentation.

Examples/test-suite/li_std_auto_ptr.i

@@ -0,0 +1,56 @@
+%module li_std_auto_ptr
+
+#if defined(SWIGCSHARP) || defined(SWIGJAVA) || defined(SWIGPYTHON)
+
+%include "std_auto_ptr.i"
+
+%auto_ptr(Klass)
+
+%inline %{
+
+#include <memory>
+#include <string>
+#include "swig_examples_lock.h"
+
+class Klass {
+public:
+  explicit Klass(const char* label) :
+    m_label(label)
+  {
+    SwigExamples::Lock lock(critical_section);
+    total_count++;
+  }
+
+  const char* getLabel() const { return m_label.c_str(); }
+
+  ~Klass()
+  {
+    SwigExamples::Lock lock(critical_section);
+    total_count--;
+  }
+
+  static int getTotal_count() { return total_count; }
+
+private:
+  static SwigExamples::CriticalSection critical_section;
+  static int total_count;
+
+  std::string m_label;
+};
+
+SwigExamples::CriticalSection Klass::critical_section;
+int Klass::total_count = 0;
+
+%}
+
+%template(KlassAutoPtr) std::auto_ptr<Klass>;
+
+%inline %{
+
+std::auto_ptr<Klass> makeKlassAutoPtr(const char* label) {
+  return std::auto_ptr<Klass>(new Klass(label));
+}
+
+%}
+
+#endif