Added encyclopedic info

lib/python/Products/ZSQLMethods/SQL.py

@@ -11,13 +11,17 @@
 __doc__='''SQL Methods
 
 
-$Id: SQL.py,v 1.2 1998/02/23 19:00:31 jim Exp $'''
-__version__='$Revision: 1.2 $'[11:-2]
+$Id: SQL.py,v 1.3 1998/03/18 20:57:57 jim Exp $'''
+__version__='$Revision: 1.3 $'[11:-2]
 
 import AqueductDA.DA
 from Globals import HTMLFile
 
 def SQLConnectionIDs(self):
+    """Find SQL database connections in the current folder and above
+
+    This function return a list of ids.
+    """
     ids={}
     have_id=ids.has_key
     StringType=type('')
@@ -44,11 +48,59 @@ manage_addAqueductSQLMethodForm=HTMLFile('add', globals())
 def manage_addAqueductSQLMethod(self, id, title,
 				connection_id, arguments, template,
 				REQUEST=None):
-    """Add a SQL Method to a folder"""
+    """Add an SQL Method
+
+    The 'connection_id' argument is the id of a database connection
+    that resides in the current folder or in a folder above the
+    current folder.  The database should understand SQL.
+
+    The 'arguments' argument is a string containing an arguments
+    specification, as would be given in the SQL method cration form.
+
+    The 'template' argument is a string containing the source for the
+    SQL Template.
+    """
     self._setObject(id, SQL(id, title, connection_id, arguments, template))
     if REQUEST is not None: return self.manage_main(self,REQUEST)
 
 class SQL(AqueductDA.DA.DA):
+    """SQL Database methods
+
+    SQL Database methods are used to access external SQL databases.
+
+    They support three important Principia abstractions:
+
+      - Method
+
+        SQL Methods behave like methods of the folders they are
+	accessed in.  In particular, they can be used from other
+	methods, like Documents, ExternalMethods, and even other SQL
+	Methods.
+
+      - Searchability
+
+        Database methods support the Principia Searchable Object
+        Interface.  Search interface wizards can be used to build user
+        interfaces to them.  They can be used in joins and
+        unions. They provide meta-data about their input parameters
+        and result data.
+
+	For more information, see the searchable-object interface
+	specification. 
+
+      - Containment
+
+        Database methods support URL traversal to access and invoke
+        methods on individual record objects. For example, suppose you
+        had an 'employees' database method that took a single argument
+        'employee_id'.  Suppose that employees had a 'service_record'
+        method (defined in a record class or acquired from a
+        folder). The 'service_record' method could be accessed with a
+        URL like::
+
+	   employees/employee_id/1234/service_record
+
+    """
     meta_type='Aqueduct SQL Database Method'
     icon='misc_/AqueductSQLMethods/icon'
 		
@@ -59,6 +111,9 @@ class SQL(AqueductDA.DA.DA):
 ############################################################################## 
 #
 # $Log: SQL.py,v $
+# Revision 1.3  1998/03/18 20:57:57  jim
+# Added encyclopedic info
+#
 # Revision 1.2  1998/02/23 19:00:31  jim
 # updated permissions
 #