more docs

basis/db/db-docs.factor

@@ -150,8 +150,9 @@ ARTICLE: "db-custom-database-combinators" "Custom database combinators"
 
 "Make a " { $snippet "with-" } " word to open, close, and use your database."
 { $code <"
+USING: db.sqlite db io.files ;
 : with-my-database ( quot -- )
-    { "my-database.db" temp-file } 
+    { "my-database.db" temp-file } sqlite-db rot with-db ;
 "> }
 
 

basis/db/tuples/tuples-docs.factor

@@ -82,9 +82,9 @@ HELP: count-tuples
 
 HELP: query
 { $values
-     { "tuple" null } { "query" null }
+     { "tuple" tuple } { "query" query }
-     { "tuples" null } }
+     { "tuples" "a sequence of tuples" } }
-{ $description "" } ;
+{ $description "Allows for queries with group by, order by, limit, and offset clauses.  " } ;
 
 { select-tuple select-tuples count-tuples query } related-words
 

basis/db/tuples/tuples.factor

@@ -50,10 +50,10 @@ HOOK: insert-tuple* db ( tuple statement -- )
 
 GENERIC: eval-generator ( singleton -- obj )
 
-: resulting-tuple ( class row out-params -- tuple )
+: resulting-tuple ( exemplar-tuple row out-params -- tuple )
     rot class new [
         [
-            >r slot-name>> r> set-slot-named
+            [ slot-name>> ] dip set-slot-named
         ] curry 2each
     ] keep ;
 
@@ -65,7 +65,7 @@ GENERIC: eval-generator ( singleton -- obj )
 : query-modify-tuple ( tuple statement -- )
     [ query-results [ sql-row-typed ] with-disposal ] keep
     out-params>> rot [
-        >r slot-name>> r> set-slot-named
+        [ slot-name>> ] dip set-slot-named
     ] curry 2each ;
 
 : with-disposals ( seq quot -- )
@@ -121,7 +121,7 @@ GENERIC: eval-generator ( singleton -- obj )
     [ [ bind-tuple ] [ query-tuples ] 2bi ] with-disposal ;
 
 : query ( tuple query -- tuples )
-    >r dup dup class r> <query> do-select ;
+    [ dup dup class ] dip <query> do-select ;
 
 : select-tuples ( tuple -- tuples )
     dup dup class <select-by-slots-statement> do-select ;

basis/db/types/types-docs.factor

@@ -13,7 +13,7 @@ HELP: +autoincrement+
 { $description "" } ;
 
 HELP: +db-assigned-id+
-{ $description "" } ;
+{ $description "The database assigns a primary key to the object.  The primary key is most likely a big integer, but is database-dependent." } ;
 
 HELP: +default+
 { $description "" } ;
@@ -34,7 +34,7 @@ HELP: +primary-key+
 { $description "" } ;
 
 HELP: +random-id+
-{ $description "" } ;
+{ $description "Factor chooses a random number and tries to insert the tuple into the database with this number as its primary key.  The default number of retries to find a unique random number is 10, though in practice it will almost certainly succeed on the first try." } ;
 
 HELP: +serial+
 { $description "" } ;
@@ -43,7 +43,7 @@ HELP: +unique+
 { $description "" } ;
 
 HELP: +user-assigned-id+
-{ $description "" } ;
+{ $description "The user is responsible for choosing a primary key for tuples inserted with this database type.  Keys must be unique or else the database will throw an error.  Usually it is better to use a " { $link +db-assigned-id+ } "." } ;
 
 HELP: <generator-bind>
 { $description "" } ;
@@ -55,22 +55,22 @@ HELP: <low-level-binding>
 { $description "" } ;
 
 HELP: BIG-INTEGER
-{ $description "" } ;
+{ $description "A 64-bit integer." } ;
 
 HELP: BLOB
-{ $description "" } ;
+{ $description "A serialized Factor object.  The database library automatically serializes the object for a SQL insert or update and deserializes it on a tuple query." } ;
 
 HELP: BOOLEAN
-{ $description "" } ;
+{ $description "Either true or false." } ;
 
 HELP: DATE
-{ $description "" } ;
+{ $description "A date without a time component." } ;
 
 HELP: DATETIME
-{ $description "" } ;
+{ $description "A date and a time." } ;
 
 HELP: DOUBLE
-{ $description "" } ;
+{ $description "Corresponds to Factor's 64bit floating-point numbers." } ;
 
 HELP: FACTOR-BLOB
 { $description "" } ;
@@ -85,7 +85,7 @@ HELP: REAL
 { $description "" } ;
 
 HELP: SIGNED-BIG-INTEGER
-{ $description "" } ;
+{ $description "For portability, if a number is known to be 64bit and signed, then this datatype may be used.  Some databases, like SQLite, cannot store arbitrary bignums as BIGINT types.  If storing arbitrary bignums, use " { $link FACTOR-BLOB } "." } ;
 
 HELP: TEXT
 { $description "" } ;
@@ -297,7 +297,34 @@ HELP: unknown-modifier
 { $description "" } ;
 
 ARTICLE: "db.types" "Database types"
-"The " { $vocab-link "db.types" } " vocabulary maps Factor types to database types."
+"The " { $vocab-link "db.types" } " vocabulary maps Factor types to database types." $nl
+"Primary keys:"
+{ $subsection +db-assigned-id+ }
+{ $subsection +user-assigned-id+ }
+{ $subsection +random-id+ }
+"Null and boolean types:"
+{ $subsection NULL }
+{ $subsection BOOLEAN }
+"Text types:"
+{ $subsection VARCHAR }
+{ $subsection TEXT }
+"Number types:"
+{ $subsection INTEGER }
+{ $subsection BIG-INTEGER }
+{ $subsection SIGNED-BIG-INTEGER }
+{ $subsection UNSIGNED-BIG-INTEGER }
+{ $subsection DOUBLE }
+{ $subsection REAL }
+"Calendar types:"
+{ $subsection DATE }
+{ $subsection DATETIME }
+{ $subsection TIME }
+{ $subsection TIMESTAMP }
+"Arbitrary Factor objects:"
+{ $subsection BLOB }
+{ $subsection FACTOR-BLOB }
+"Factor URLs:"
+{ $subsection URL }
 ;
 
 ABOUT: "db.types"