attribute library documentation edits

Doc/Manual/Contents.html

@@ -449,6 +449,7 @@
 <li><a href="Library.html#Library_nn16">Utility Libraries</a>
 <ul>
 <li><a href="Library.html#Library_nn17">exception.i</a>
+<li><a href="Library.html#Library_attributes">attribute.i</a>
 </ul>
 </ul>
 </div>

Doc/Manual/Library.html

@@ -44,7 +44,7 @@
 <li><a href="#Library_nn16">Utility Libraries</a>
 <ul>
 <li><a href="#Library_nn17">exception.i</a>
-<li><a href="#Library_Attributes">attribute.i</a>
+<li><a href="#Library_attributes">attribute.i</a>
 </ul>
 </ul>
 </div>
@@ -2109,9 +2109,14 @@ For example:
 </div>
 
 
-<H3><a name="Library_Attributes">12.5.2 attribute.i</a></H3>
+<H3><a name="Library_attributes">12.5.2 attribute.i</a></H3>
 
 
+<p>
+The attribute library contains a set of macros to convert a pair of set/get methods
+into a "native" attribute/property.
+</p>
+
 <p>
 Use <tt>%attribute</tt> when you have a pair of get/set methods to a
 primitive type like:
@@ -2122,8 +2127,7 @@ primitive type like:
 %include "attribute.i"
 %attribute(A, int, a, get_a, set_a);
 
-struct A
+struct A {
-{
   int get_a() const;
   void set_a(int aa);
 };
@@ -2132,8 +2136,21 @@ struct A
 
 <p>
 and you want to provide that variable as an attribute in the target
-langage.  This examples only works for primitive types, not derived
+langage.  This example only works for primitive types, not derived
-types.  If you don't provide a 'set' method, a 'read-only' attribute
+types.
+Now you can use the attributes like so (in Python):
+</p>
+
+<div class="targetlang">
+<pre>
+x = A()
+x.a = 3        # calls A::set_a(3)
+print(x.a)     # calls A::get_a() const
+</pre>
+</div>
+
+<p>
+If you don't provide a 'set' method, a 'read-only' attribute
 is generated, ie, like:
 </p>
 
@@ -2152,21 +2169,31 @@ access methods for primitive types or class/structs, like:
 <pre>
 %attributeref(A, int, b);
 
-struct A
+struct A {
-{
+  const int &amp; b() const;
-  const int& b() const;
+  int &amp; b();
-  int& b();
 };
 
 %attributeref(B, int, c);
 
-struct B
+struct B {
-{
+  int &amp; c();
-  int& c();
 };
 </pre>
 </div>
 
+<p>
+Use the attributes like so (in Python):
+</p>
+
+<div class="targetlang">
+<pre>
+x = A()
+x.b = 3        # calls A::b()
+print(x.b)     # calls A::b() const
+</pre>
+</div>
+
 <p>
 You can also use
 </p>
@@ -2193,25 +2220,10 @@ is the same as the last example, but instead of the attribute 'c' being
 called 'c', it is called 'd'.
 </p>
 
-<p>
-Now you can use the attributes like so:
-</p>
-
-<div class="code">
-<pre>
-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
-</pre>
-</div>
-
 <p>
 Use <tt>%attribute2</tt> instead of <tt>%attribute</tt> to indicate
-that reference-pointer translation is required. You
+that reference-pointer translation is required.
-use <tt>%attribute2</tt> instead of <tt>%attribute</tt> in cases like
+Use <tt>%attribute2</tt> instead of <tt>%attribute</tt> in cases like
 this:
 </p>
 
@@ -2225,18 +2237,18 @@ this:
   class MyClass {
     MyFoo foo;
   public:
-    MyFoo& GetFoo() { return foo; }
+    MyFoo &amp; GetFoo() { return foo; }
-    void SetFoo(const MyFoo& other) { foo = other; }
+    void SetFoo(const MyFoo &amp;other) { foo = other; }
   };
 %}
 </pre>
 </div>
 
 <p>
-Here, the data type of the property is a wrapped type (MyFoo) and on
+Here, the data type of the property is a wrapped type <tt>MyFoo</tt> 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
+with the reference type of the accessors (MyFoo &amp;). Therefore, if you
 use <tt>%attribute</tt>, you'll get an error from your C/C++
 compiler. <tt>%attribute2</tt> translates between a pointer and a
 reference to eliminate the error. In case you're confused, let's make
@@ -2247,12 +2259,12 @@ try <tt>%attribute2</tt> instead.
 
 <p>
 NOTE: remember that if the type contains commas, such as
-'std::pair<int,int>', you need to use the macro like:
+<tt>std::pair&lt;int, int&gt;</tt>, you need to use the macro like:
 </p>
 
 <div class="code">
 <pre>
-%attributeref(A, %arg(std::pair<int,int>), pval);
+%attributeref(A, %arg(std::pair&lt;int, int&gt;), pval);
 </pre>
 </div>
 
@@ -2275,10 +2287,10 @@ access is by value rather than reference.
 %attributeval(MyClassVal, MyFoo, ReadOnlyFoo, GetFoo);
 %inline %{
   class MyClassVal {
-	MyFoo foo;
+    MyFoo foo;
   public:
-	MyFoo GetFoo() { return foo; }
+    MyFoo GetFoo() { return foo; }
-	void SetFoo(MyFoo other) { foo = other; }
+    void SetFoo(MyFoo other) { foo = other; }
   };
 %}
 </pre>
@@ -2288,21 +2300,21 @@ access is by value rather than reference.
 The <tt>%attributestring</tt> is the same as <tt>%attributeval</tt>,
 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:
+in the target language. Example usage for <tt>std::string</tt>:
 </p>
 
 <div class="code">
 <pre>
-%include <std_string.i>
+%include &lt;std_string.i&gt;
 %attributestring(MyStringyClass, std::string, ReadWriteString, GetString, SetString);
 %attributestring(MyStringyClass, std::string, ReadOnlyString, GetString);
 %inline %{
   class MyStringyClass {
-	std::string str;
+    std::string str;
   public:
-	MyStringyClass(const std::string &val) : str(val) {}
+    MyStringyClass(const std::string &amp;val) : str(val) {}
-	std::string GetString() { return str; }
+    std::string GetString() { return str; }
-	void SetString(std::string other) { str = other; }
+    void SetString(std::string other) { str = other; }
   };
 %}
 </pre>
@@ -2312,7 +2324,7 @@ in the target language. Example usage for std::string:
 The <tt>%attributestring</tt> also works for class types that
 have <tt>%naturalvar</tt> turned on and so is also useful for
 shared_ptr which has <tt>%naturalvar</tt> turned on in
-<tt>%shared</tt>_ptr.
+<tt>%shared_ptr</tt>.
 </p>
 
 

Doc/Manual/SWIG.html

@@ -2776,7 +2776,7 @@ void Foo_w_set(FOO *f, WORD value) {
 <p>
 If you have accessor methods that you want to use as attributes in the
 target language, you can make them appear as data members using
-<a href="Library.html#Library_Attributes">attributes.i</a>.
+<a href="Library.html#Library_attributes">attributes.i</a>.
 </p>
 
 <p>