Added documentation.

[SVN r17405]

src/build/property-set.jam

@@ -7,6 +7,18 @@ import class : class new ;
 import feature ;
 import sequence ;
 
+# Class for storing a set of properties.
+# - there's 1<->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.
+# 
+# - each property is classified as either base, free, dependency or incidental,
+#   and it's possible to efficiently obtain properties of each class.
+#
+# - several operations, like and refine and as-path are provided. They all use
+#   caching whenever possible.
+#
 local rule property-set ( raw-properties * )
 {
     self.raw = $(raw-properties) ;
@@ -40,31 +52,32 @@ local rule property-set ( raw-properties * )
         }                        
     }
     
-    
-    
+    # Returns Jam list of stored properties
     rule raw ( )
     {
         return $(self.raw) ;
     }
     
+    # Returns properties that are neither incidental nor free
     rule base ( )
     {
         return $(self.base) ;
     }
     
     
+    # Returns free properties which are not dependency properties
     rule free ( )
     {
         return $(self.free) ;
     }
     
-    
+    # Returns dependency properties
     rule dependency ( )
     {
         return $(self.dependency) ;
     }
     
-    
+    # Returns incidental properties
     rule incidental ( )
     {
         return $(self.incidental) ;
@@ -136,6 +149,8 @@ local rule property-set ( raw-properties * )
 
 class property-set ;
 
+# Creates new 'property-set' instance for the given raw properties,
+# or returns an already existing ones.
 rule create ( raw-properties * )
 {
 # If we uncomment this one, we'll end up with paths like    
@@ -157,6 +172,7 @@ rule create ( raw-properties * )
 
 .empty = [ create ] ;
 
+# Returns property-set with empty set of properties.
 rule empty ( )
 {
     return $(.empty) ;