Index: openacs-4/packages/acs-object-management/tcl/cache-init.tcl
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-object-management/tcl/cache-init.tcl,v
diff -u -r1.2 -r1.3
--- openacs-4/packages/acs-object-management/tcl/cache-init.tcl	13 Aug 2009 00:15:05 -0000	1.2
+++ openacs-4/packages/acs-object-management/tcl/cache-init.tcl	14 Aug 2009 01:06:08 -0000	1.3
@@ -4,6 +4,12 @@
     changing the value of the package parameter DBCacheSize and restarting
     your server.
 
+    Cache keys in the object Tcl API have the following form:
+
+    t::object_type::query_name For all queries dealing with the specified object type.
+    v::object_view::query_name For all queries dealing with the specified object view.
+    o::object_id::query_name For all queries dealing with the specified object.
+
     @creation-date 30 June 2009
     @author Don Baccus (dhogaza@pacifier.com)
     @cvs-id $Id$
Index: openacs-4/packages/acs-object-management/tcl/object-procs.tcl
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-object-management/tcl/object-procs.tcl,v
diff -u -r1.2 -r1.3
--- openacs-4/packages/acs-object-management/tcl/object-procs.tcl	13 Aug 2009 00:15:05 -0000	1.2
+++ openacs-4/packages/acs-object-management/tcl/object-procs.tcl	14 Aug 2009 01:06:08 -0000	1.3
@@ -158,8 +158,10 @@
 
     if { [info exists attributes] } {
         array set attributes_array $attributes
-    } else {
+    } elseif { [info exists array] } {
         upvar $array attributes_array
+    } else {
+        array set attributes_array {}
     }
 
     set attributes_array(object_type) $object_type
Index: openacs-4/packages/acs-object-management/tcl/object-type-procs.tcl
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-object-management/tcl/object-type-procs.tcl,v
diff -u -r1.2 -r1.3
--- openacs-4/packages/acs-object-management/tcl/object-type-procs.tcl	13 Aug 2009 00:15:05 -0000	1.2
+++ openacs-4/packages/acs-object-management/tcl/object-type-procs.tcl	14 Aug 2009 01:06:08 -0000	1.3
@@ -24,6 +24,35 @@
     {-dynamic_p t}
     -attributes
 } {
+
+    Create a new object type, with an initial set of attributes.  Optionally create
+    the type's SQL table and type attribute SQL columns.
+
+    For detailed information on the various parameters to this procedure, please
+    read the developer's documentation for the SQL procedures which do the actual
+    type and attribute creation.
+
+    @param object_type The name of the type to create.
+    @param pretty_name The human-readable name of the type to create.
+    @param pretty_plural Plural human-readable name of the type to create.
+    @param supertype Supertype of the type to create (default "acs_object").
+    @param table_name Optional name of the associated SQL table for the new type.  Default
+           will be the name of the new type appended with "_t".
+    @param package_name Optional name of the associated SQL package used to manipulate
+           objects of this type.  Note: the acs-object-management does it with a Tcl API.
+    @param abstract_p If true, the type's abstract (no attributes).
+    @param type_extension_table Optional table to extend acs_object_types information for
+           the new type.  Rarely used.  Probably shouldn't be used.
+    @param name_method Optional name of a SQL procedure which returns the name of an object
+           of this type.
+    @param create_table_p If true, create the table and attribute columns automatically.
+           Defaults to false for backwards compatibility with existing ways of doing things,
+           but having this procedure create the SQL table and columns is commended and
+           convenient.
+    @param dynamic_p If true, it's a dynamic type that can be manipulated by the admin UI.
+    @param attributes A list of attributes and their qualifiers of the form:
+           \{ attr_name \{ (qualifiers in array get format) \}
+           \{ attr_name_2 \{ (qualifers) \}
 } {
     set var_list [list \
         [list object_type $object_type] \
@@ -52,8 +81,8 @@
                     lappend params -$param
                     lappend params $value
                 }
+                eval [concat object_type::attribute::new $params]
             }
-            eval [concat object_type::attribute::new $params]
         }
         package_exec_plsql \
             -var_list [list [list object_type $object_type]] acs_object_type refresh_view
@@ -66,14 +95,22 @@
     {-drop_table_p f}
     {-drop_children_p f}
 } {
+
+    Delete an object type, and optionally its subtypes and any other tables or views
+    which depend on it.
+
+    @param object_type The object type to delete.
+    @param cascade_p If true, append "cascade" to the SQL drop table command.
+    @param drop_table_p If true (recommended) drop the table associated with the object type.
+    @param drop_children_p If true (recommended) drop all subtypes dependent on this type.
+} {
     set var_list [list \
         [list object_type $object_type] \
         [list cascade_p $cascade_p] \
         [list drop_table_p $drop_table_p] \
         [list drop_children_p $drop_children_p]]
     package_exec_plsql -var_list $var_list acs_object_type drop_type
     object_type::flush_cache -object_type $object_type
-    object_view::flush_cache -object_view *
 }
 
 ad_proc -public object_type::get {
@@ -95,6 +132,9 @@
       <li>type_extension_table,
       <li>dynamic_p
     </ul>
+
+    @param object_type The object type whose metadata should be returned.
+    @param array The name of the output array to hold the metadata.
 } {
     upvar 1 $array row
     db_1row -cache_pool acs_metadata -cache_key t::${object_type}::get \
@@ -105,6 +145,13 @@
     -object_type:required
     -element:required
 } {
+
+    Return one metadata element for an object type, i.e. pretty name etc.
+
+    @param object_type The object type whose metadata should be returned.
+    @param element The name of the element desired.
+
+    @return The value for the metadata element for the given object type.
 } {
     object_type::get -object_type $object_type -array object_type_info
     return $object_type_info($element)
@@ -113,6 +160,15 @@
 ad_proc object_type::get_root_view {
     -object_type:required
 } {
+
+    Return the name of the root view for the given object type.  The root view is created by
+    object_type::new (actually the underlying SQL procedure create_type) and contains all
+    attributes declared for the type and its supertypes, along with the innermost
+    tree_sortkey for PG types, and the object id.
+
+    @param object_type The type whose root view should be returned.
+
+    @return The name of the root view for the type.
 } {
     return [db_string -cache_pool acs_metadata -cache_key t::${object_type}::get_root_view \
       select_root_view {}]
@@ -170,6 +226,16 @@
 ad_proc -public object_type::flush_cache {
     -object_type:required
 } {
+    Flush the cache of all query resultsets which depend on the object type.  See cache-init.tcl
+    for the cache key naming scheme which must be followed.  This very aggressively flushes
+    all view and object queries (since the related object_type isn't tracked in the cache_key)
+    but since type creation and modification operations are relatively infrequent, there's
+    not much motifivation to be clever about it.
+
+    @param object_type The object type whose query resultsets should be flushed from the
+           cache.
 } {
     db_flush_cache -cache_pool acs_metadata -cache_key_pattern t::${object_type}::*
+    db_flush_cache -cache_pool acs_metadata -cache_key_pattern v::*
+    db_flush_cache -cache_pool acs_metadata -cache_key_pattern o::*
 }
Index: openacs-4/packages/acs-object-management/tcl/object-view-procs.tcl
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-object-management/tcl/object-view-procs.tcl,v
diff -u -r1.2 -r1.3
--- openacs-4/packages/acs-object-management/tcl/object-view-procs.tcl	13 Aug 2009 00:15:05 -0000	1.2
+++ openacs-4/packages/acs-object-management/tcl/object-view-procs.tcl	14 Aug 2009 01:06:08 -0000	1.3
@@ -13,10 +13,19 @@
 namespace eval object_type::view::attribute {}
 
 ad_proc object_type::view::new {
-    -object_type:required
     -object_view:required
     -pretty_name:required
+    -object_type:required
 } {
+
+    Create the metadata for a new view for an object type.  As of now, this
+    procedure doesn't allow for the creation of attributes (the paradigm is to
+    copy attributes from the type's root view), so it doesn't physically create
+    the SQL view.  This will be done as attributes are added.
+
+    @param object_view The name of the new view.
+    @param pretty_name The human-readable name of the new view.
+    @param object_type The object type the view's being built for.
 } {
     db_dml insert_object_view {}
     object_type::flush_cache -object_type $object_type
@@ -25,15 +34,24 @@
 ad_proc object_type::view::delete {
     -object_view:required
 } {
+    Delete a view, both the metadata and SQL view.
+
+    @param object_view The name of the view to delete.
 } {
     object_type::view::flush_cache -object_view $object_view
     db_dml delete_object_view {}
+    db_dml drop_view {}
 }
 
 ad_proc object_type::view::get {
     -object_view:required
     -array:required
 } {
+    Get the metadata information for a view, and return it in an array in the
+    caller's namespace.
+
+    @param object_view The object view whose metadata should be returned.
+    @param array The name of the output array to hold the result.
 } {
     upvar $array local
     db_1row -cache_pool acs_metadata -cache_key v::${object_view}::get \
@@ -44,6 +62,10 @@
     -object_view:required
     -element:required
 } {
+    Return one metadata element for an object view.
+
+    @param object_view The object view whose metadata should be returned.
+    @param element The name of the metadata element to return (pretty_name, etc).
 } {
     object_type::view::get -object_view $object_view -array view
     return $view($element)
@@ -52,6 +74,12 @@
 ad_proc object_type::view::flush_cache {
     -object_view:required
 } {
+    Flush all queries dependent on a view.  This also flushes queries dependent on the
+    view's type, as when we delete a view (for instance) the set of views belonging to a
+    type changes.
+
+    @param object_view The view to flush.
+} {
     object_type::flush_cache -object_type [object_type::view::get_element \
                                               -object_view $object_view \
                                               -element object_type]
Index: openacs-4/packages/acs-object-management/tcl/object-view-procs.xql
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-object-management/tcl/object-view-procs.xql,v
diff -u -r1.2 -r1.3
--- openacs-4/packages/acs-object-management/tcl/object-view-procs.xql	13 Aug 2009 00:15:05 -0000	1.2
+++ openacs-4/packages/acs-object-management/tcl/object-view-procs.xql	14 Aug 2009 01:06:08 -0000	1.3
@@ -17,6 +17,12 @@
     </querytext>
   </fullquery>
 
+  <fullquery name="object_type::view::delete.drop_view">
+    <querytext>
+      drop view :object_view
+    </querytext>
+  </fullquery>
+
   <fullquery name="object_type::view::get.get_object_view">
     <querytext>
       select *
Index: openacs-4/packages/acs-object-management/tcl/view-attribute-procs.tcl
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-object-management/tcl/view-attribute-procs.tcl,v
diff -u -r1.1 -r1.2
--- openacs-4/packages/acs-object-management/tcl/view-attribute-procs.tcl	13 Aug 2009 00:15:05 -0000	1.1
+++ openacs-4/packages/acs-object-management/tcl/view-attribute-procs.tcl	14 Aug 2009 01:06:08 -0000	1.2
@@ -15,8 +15,11 @@
     -from_object_view
     -attribute_id:required
 } {
+    @param to_object_view The object view to copy the attribute to.
+    @param from_object_view The object view to copy the attribute from.  Defaults to the
+           root view for the underlying object type.
+    @param attribute_id The attribute_id to copy.
 } {
-
     set object_type \
         [object_type::view::get_element -object_view $to_object_view -element object_type]
    
@@ -32,6 +35,10 @@
     -object_view:required
     -attribute_id:required
 } {
+    Delete an object view attribute.
+
+    @param object_view:required
+    @param attribute_id:required
 } {
     db_dml delete {}
     object_type::view::flush_cache -object_view $object_view