Document the property-set class.

[SVN r77818]

v2/doc/src/extending.xml

@@ -83,11 +83,13 @@
         
         <para>The <link linkend="bbv2.reference.class.abstract-target.generate">generate</link>
         method takes the build properties
-        (as an instance of the <classname>property-set</classname> class) and returns
+        (as an instance of the <link linkend="bbv2.reference.class.property-set">
+        property-set</link> class) and returns
         a list containing:</para>
         <itemizedlist>
           <listitem><para>As front element&mdash;Usage-requirements from this invocation
-          (an instance of <classname>property-set</classname>)</para></listitem>
+          (an instance of <link linkend="bbv2.reference.class.property-set">
+          property-set</link>)</para></listitem>
           <listitem><para>As subsequent elements&mdash;created concrete targets (
           instances of the <classname>virtual-target</classname> class.)</para></listitem>
         </itemizedlist>
@@ -158,8 +160,8 @@
         subclass is <classname>file-target</classname>. A file target is associated
         with an action that creates it&mdash; an instance of the <classname>action</classname>
         class. The action, in turn, hold a list of source targets. It also holds the 
-        <classname>property-set</classname> instance with the build properties that
-        should be used for the action.</para>
+        <link linkend="bbv2.reference.class.property-set">property-set</link>
+        instance with the build properties that should be used for the action.</para>
 
         <para>Here's an example of creating a target from another target, <code>source</code></para>
 <programlisting>

v2/doc/src/property-set.xml

@@ -0,0 +1,128 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
+  "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+
+<section id="bbv2.reference.class.property-set">
+
+  <title>Class property-set</title>
+  <indexterm>
+    <primary>property-set</primary>
+  </indexterm>
+
+  <para>Class for storing a set of properties.</para>
+
+<programlisting language="jam">
+class property-set {
+    rule <link linkend="bbv2.reference.class.property-set.raw">raw</link> ( )
+    rule <link linkend="bbv2.reference.class.property-set.str">str</link> ( )
+    rule <link linkend="bbv2.reference.class.property-set.propagated">propagated</link> ( )
+    rule <link linkend="bbv2.reference.class.property-set.add">add</link> ( ps )
+    rule <link linkend="bbv2.reference.class.property-set.add-raw">add-raw</link> ( properties * )
+    rule <link linkend="bbv2.reference.class.property-set.refine">refine</link> ( ps )
+    rule <link linkend="bbv2.reference.class.property-set.get">get</link> ( feature )
+}
+</programlisting>
+
+  <para>
+    There is 1&lt;-&gt;1 correspondence between identity and value. No two instances
+    of the class are equal. To maintain this property, the 'property-set.create'
+    rule should be used to create new instances. Instances are immutable.
+  </para>
+
+  <orderedlist>
+
+    <listitem id="bbv2.reference.class.property-set.raw">
+      <indexterm zone="bbv2.reference.class.property-set.raw">
+        <primary>raw</primary>
+        <secondary>Property Set Method</secondary>
+      </indexterm>
+      <code language="jam">rule raw ( )</code>
+      <para>Returns a Jam list of the stored properties.</para>
+    </listitem>
+
+    <listitem id="bbv2.reference.class.property-set.str">
+      <indexterm zone="bbv2.reference.class.property-set.str">
+        <primary>str</primary>
+        <secondary>Property Set Method</secondary>
+      </indexterm>
+      <code language="jam">rule str ( )</code>
+      <para>Returns the string repesentation of the stored properties.</para>
+    </listitem>
+
+    <listitem id="bbv2.reference.class.property-set.propagated">
+      <indexterm zone="bbv2.reference.class.property-set.propagated">
+        <primary>propagated</primary>
+        <secondary>Property Set Method</secondary>
+      </indexterm>
+      <code language="jam">rule propagated ( )</code>
+      <para>
+        Returns a <link linkend="bbv2.reference.class.property-set">property-set</link>
+        containing all the <link linkend="bbv2.reference.features.attributes.propagated">propagated</link>
+        properties in this <link linkend="bbv2.reference.class.property-set">property-set</link>.
+      </para>
+    </listitem>
+
+    <listitem id="bbv2.reference.class.property-set.add">
+      <indexterm zone="bbv2.reference.class.property-set.add">
+        <primary>add</primary>
+        <secondary>Property Set Method</secondary>
+      </indexterm>
+      <code language="jam">rule add ( ps )</code>
+      <para>
+        Returns a new <link linkend="bbv2.reference.class.property-set">
+        property-set</link> containing the union of the properties
+        in this <link linkend="bbv2.reference.class.property-set">
+        property-set</link> and in <literal>ps</literal>.
+        <note>
+          <para>
+            If <literal>ps</literal> contains non-free properties
+            that should override the values in this object, use
+            <link linkend="bbv2.reference.class.property-set.refine">
+            refine</link> instead.
+          </para>
+        </note>
+      </para>
+    </listitem>
+
+    <listitem id="bbv2.reference.class.property-set.add-raw">
+      <indexterm zone="bbv2.reference.class.property-set.add-raw">
+        <primary>add-raw</primary>
+        <secondary>Property Set Method</secondary>
+      </indexterm>
+      <code language="jam">rule add-raw ( properties * )</code>
+      <para>
+        Link <link linkend="bbv2.reference.class.property-set.add">
+        add</link>, except that it takes a list of properties
+        instead of a <link linkend="bbv2.reference.class.property-set">
+        property-set</link>.
+      </para>
+    </listitem>
+
+    <listitem id="bbv2.reference.class.property-set.refine">
+      <indexterm zone="bbv2.reference.class.property-set.refine">
+        <primary>refine</primary>
+        <secondary>Property Set Method</secondary>
+      </indexterm>
+      <code language="jam">rule refine ( ps )</code>
+      <para>
+        Refines properties by overriding any non-free and non-conditional
+        properties for which a different value is specified in
+        <literal>ps</literal>. Returns the resulting
+        <link linkend="bbv2.reference.class.property-set">property-set</link>.
+      </para>
+    </listitem>
+
+    <listitem id="bbv2.reference.class.property-set.get">
+      <indexterm zone="bbv2.reference.class.property-set.get">
+        <primary>get</primary>
+        <secondary>Property Set Method</secondary>
+      </indexterm>
+      <code language="jam">rule get ( feature )</code>
+      <para>
+        Returns all the values of <literal>feature</literal>.
+      </para>
+    </listitem>
+
+  </orderedlist>
+  
+</section>

v2/doc/src/reference.xml

@@ -1959,6 +1959,7 @@ import path : native make : native-path make-path ;
     <xi:include href="project-target.xml"/>
     <xi:include href="main-target.xml"/>
     <xi:include href="basic-target.xml"/>
+    <xi:include href="property-set.xml"/>
   </section>
 
   <section id="bbv2.reference.buildprocess">