Index: openacs-4/packages/acs-service-contract/tcl/contract-procs.tcl
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-service-contract/tcl/contract-procs.tcl,v
diff -u -N -r1.2.2.1 -r1.2.2.2
--- openacs-4/packages/acs-service-contract/tcl/contract-procs.tcl	5 Mar 2003 14:52:43 -0000	1.2.2.1
+++ openacs-4/packages/acs-service-contract/tcl/contract-procs.tcl	13 May 2003 12:14:37 -0000	1.2.2.2
@@ -39,8 +39,80 @@
 ad_proc -public acs_sc::contract::new_from_spec {
     {-spec:required}
 } {
-    Takes a complete notification spec and parses the 
-    name, description and operations
+    Takes a complete service contract specification and creates the new service contract.
+
+    <p>
+    
+    The spec looks like this:
+
+    <blockquote><pre>
+    set spec {
+        name "Action_SideEffect"
+        description "Get the name of the side effect to create action"
+        operations {
+            GetObjectTypes {
+                description "Get the object types for which this implementation is valid."
+                output { object_types:string,multiple }
+                iscachable_p "t"
+            }
+            GetPrettyName { 
+                description "Get the pretty name of this implementation."
+                output { pretty_name:string }
+                iscachable_p "t"
+            }
+            DoSideEffect {
+                description "Do the side effect"
+                input {
+                    case_id:integer
+                    object_id:integer
+                    action_id:integer
+                    entry_id:integer
+                }
+            }
+        } 
+    }  
+    
+    acs_sc::contract::new_from_spec -spec $spec
+    </pre></blockquote>
+
+    Here's the detailed explanation:
+
+    <p>
+
+    The spec should be an array-list with 3 entries: 
+
+    <ul>
+      <li>name: The name of the service contract. 
+      <li>description: A human-readable descirption.
+      <li>operations: An array-list of operations in this service contract.
+    </ul>
+  
+    The operations array-list has the operation name as key, and 
+    another array-list containing the specification for the operation as the value.
+    That array-list has the following entries:
+
+    <ul>
+      <li>description: Human-readable description of the operation.
+      <li>input: Specification of the input to this operation.
+      <li>output: Specification of the output of this operation.
+      <li>iscachable_p: A 't' or 'f' for whether output from this service contract implementation
+    should automatically be cached using util_memoize.
+    </ul>
+
+    <p>
+
+    The format of the 'input' and 'output' specs is a Tcl list of parameter specs, 
+    each of which consist of name, colon (:), 
+    datatype plus an optional comma (,) and the flag 'multiple'.
+
+
+    @param spec The service contract specification as described above.
+
+    @return The contract_id of the newly created service contract.
+
+    @see util_memoize
+    @see acs_sc::invoke
+
 } {
 
     # Default values
Index: openacs-4/packages/acs-service-contract/tcl/implementation-procs.tcl
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-service-contract/tcl/implementation-procs.tcl,v
diff -u -N -r1.2.2.1 -r1.2.2.2
--- openacs-4/packages/acs-service-contract/tcl/implementation-procs.tcl	5 Mar 2003 14:52:43 -0000	1.2.2.1
+++ openacs-4/packages/acs-service-contract/tcl/implementation-procs.tcl	13 May 2003 12:14:37 -0000	1.2.2.2
@@ -46,9 +46,47 @@
 ad_proc -public acs_sc::impl::new_from_spec {
     {-spec:required}
 } {
-    Add new service contract implementation from an array-list style implementation.
+    Add new service contract implementation from an array-list style implementation, 
+    and binds it to the specified contract.
     
-    @return the ID of the new implementation
+    <p>
+
+    The specification takes the following form:
+
+    <blockquote><pre>
+    set spec {
+        contract_name "Action_SideEffect"
+        owner "bug-tracker"
+        name "CaptureResolutionCode"
+        aliases {
+            GetObjectType bug_tracker::bug::object_type
+            GetPrettyName bug_tracker::bug::capture_resolution_code::pretty_name
+            DoSideEffect  bug_tracker::bug::capture_resolution_code::do_side_effect
+        }
+    }
+    acs_sc::impl::new_from_spec -spec $spec
+    </pre></blockquote>
+
+    And here's the explanation:
+
+    <p>
+
+    The spec is an array-list with the following entries: 
+    
+    <ul>
+      <li>contract_name: The name of the service contract you're implementing.
+      <li>owner: Owner of the implementation, use the package-key.
+      <li>name: Name of your implementation.
+      <li>aliases: Specification of the tcl procedures for each of the service contract's operations.
+    </ul>
+
+    The aliases section is itself an array-list. The keys are the operation names 
+    from the service contract. The values are the names of Tcl procedures in your package, 
+    which implement these operations.
+
+    @param spec The specification for the new service contract implementation.
+    
+    @return the impl_id of the newly registered implementation
 } {
     # Spec contains: contract_name, name, owner, aliases
     array set impl $spec