Move %attribute documentation into the manual

It's fairly hidden where it is, put it where users can see it more
easily.

Fixes #2166

Lib/typemaps/attribute.swg

@@ -7,132 +7,6 @@
 /*
   The following macros convert a pair of set/get methods
   into a "native" attribute.
-
-  Use %attribute when you have a pair of get/set methods to a primitive type
-  like in:
-
-      %attribute(A, int, a, get_a, set_a);
-
-      struct A
-      {
-        int get_a() const;
-        void set_a(int aa);
-      };
-
-  If you don't provide a 'set' method, a 'read-only' attribute
-  is generated, ie, like in:
-
-      %attribute(A, int, c, get_c);
-
-  Use %attributeref when you have const/non-const reference access methods
-  for primitive types or class/structs, like in:
-
-      %attributeref(A, int, b);
-
-      struct A
-      {
-        const int& b() const;
-        int& b();
-      };
-
-      %attributeref(B, int, c);
-
-      struct B
-      {
-        int& c();
-      };
-
-  You can also use
-
-      %attributeref(Class, AttributeType, AttributeName, AccessorMethod)
-
-  if the internal C++ reference methods have a different name from the
-  attribute you want, so
-
-      %attributeref(B, int, d, c);
-
-  is the same as the last example, but instead of the attribute 'c' being
-  called 'c', it is called 'd'.
-
-  Now you can use the attributes like so:
-
-      x = A()
-      x.a = 3        # calls A::set_a
-      print x.a      # calls A::get_a
-
-      x.b = 3        # calls A::b()
-      print x.b      # calls A::b() const
-
-  Use %attribute2 instead of %attribute to indicate that reference-pointer
-  translation is required. You use %attribute2 instead of %attribute in
-  cases like this:
- 
-  %attribute2(MyClass, MyFoo, Foo, GetFoo, SetFoo);
-  %inline %{
-    struct MyFoo { 
-      int x;
-    };
-    class MyClass {
-      MyFoo foo;
-    public:
-      MyFoo& GetFoo() { return foo; }
-      void SetFoo(const MyFoo& other) { foo = other; }
-    };
-  %}
-
-  Here, the data type of the property is a wrapped type (MyFoo) and on the
-  C++ side it is passed by reference. The problem is that the SWIG wrapper will
-  pass around a pointer (MyFoo *) which is not compatible with the reference
-  type of the accessors (MyFoo &). Therefore, if you use %attribute, you'll get
-  an error from your C/C++ compiler. %attribute2 translates between a pointer
-  and a reference to eliminate the error. In case you're confused, let's make it
-  simple: just use %attribute at first, but if the C/C++ compiler gives an error
-  while compiling the wrapper, try %attribute2 instead.
-
-  NOTE: remember that if the type contains commas, such as 'std::pair<int,int>',
-  you need to use the macro like:
-
-  %attributeref(A, %arg(std::pair<int,int>), pval);
-
-  where %arg() 'normalizes' the type to be understood as a single
-  argument, otherwise the macro will get confused by the comma.
-
-  The %attributeval is the same as %attribute, but should be used when the type
-  is a class/struct (ie a non-primitive type) and when the get and set methods 
-  return/pass by value. The following is very similar to the above example, but 
-  note that the access is by value rather than reference.
-
-    %attributeval(MyClassVal, MyFoo, ReadWriteFoo, GetFoo, SetFoo);
-    %attributeval(MyClassVal, MyFoo, ReadOnlyFoo, GetFoo);
-    %inline %{
-      class MyClassVal {
-	MyFoo foo;
-      public:
-	MyFoo GetFoo() { return foo; }
-	void SetFoo(MyFoo other) { foo = other; }
-      };
-    %} 
-
-  The %attributestring is the same as %attributeval, but should be used for string
-  class types, which are unusual as they are a class on the C++ side, but normally an
-  immutable/primitive type in the target language. Example usage for std::string:
-
-    %include <std_string.i>
-    %attributestring(MyStringyClass, std::string, ReadWriteString, GetString, SetString);
-    %attributestring(MyStringyClass, std::string, ReadOnlyString, GetString);
-    %inline %{
-      class MyStringyClass {
-	std::string str;
-      public:
-	MyStringyClass(const std::string &val) : str(val) {}
-	std::string GetString() { return str; }
-	void SetString(std::string other) { str = other; }
-      };
-    %} 
-
-  The %attributestring also works for class types that have %naturalvar turned
-  on and so is also useful for shared_ptr which has %naturalvar turned on in %shared_ptr.
-
 */
 
 //