Start blocking out some documentation.

- Fix some C rdoc so it is parsed correctly.
  - Fill out transaction testing.
  - Populate docs for DB options.

FossilOrigin-Name: f54dbfacf2dda100a116fdcc856ca5231e249f23238ca9d4355618e3a380a8f8

lib/mdbx/database.rb

@@ -5,19 +5,89 @@
 require 'mdbx' unless defined?( MDBX )
 
 
-# TODO: rdoc
+# The primary class for interacting with an MDBX database.
 #
 class MDBX::Database
 
-	### Open an existing (or create a new) mdbx database at filesystem
-	### +path+.  In block form, the database is automatically closed.
+	### call-seq:
+	###    MDBX::Database.open( path ) => db
+	###    MDBX::Database.open( path, options ) => db
+	###
+	### Open an existing (or create a new) mdbx database at filesystem
+	### +path+.  In block form, the database is automatically closed
+	### when the block exits.
 	###
-	###    MDBX::Database.open( path ) -> db
-	###    MDBX::Database.open( path, options ) -> db
 	###    MDBX::Database.open( path, options ) do |db|
-	###        db[ 'key' ] #=> value
+	###        db[ 'key' ] = value
 	###    end
 	###
+	### Passing options modify various database behaviors.  See the libmdbx
+	### documentation for detailed information.
+	###
+	### ==== Options
+	###
+	### [:mode]
+	###   Whe creating a new database, set permissions to this 4 digit
+	###   octal number.  Defaults to `0644`.  Set to `0` to never automatically
+	###   create a new file, only opening existing databases.
+	###
+	### [:max_collections]
+	###   Set the maximum number of "subdatabase" collections allowed. By
+	###   default, collection support is disabled.
+	###
+	### [:max_readers]
+	###   Set the maximum number of allocated simultaneous reader slots.
+	###
+	### [:max_size]
+	###   Set an upper boundary (in bytes) for the database map size.
+	###   The default is 10485760 bytes.
+	###
+	### [:nosubdir]
+	###   When creating a new database, don't put the data and lock file
+	###   under a dedicated subdirectory.
+	###
+	### [:readonly]
+	###   Reject any write attempts while using this database handle.
+	###
+	### [:exclusive]
+	###   Access is restricted to this process handle. Other attempts
+	###   to use this database (even in readonly mode) are denied.
+	###
+	### [:compat]
+	###   Avoid incompatibility errors when opening an in-use database with
+	###   unknown or mismatched flag values.
+	###
+	### [:writemap]
+	###   Trade safety for speed for databases that fit within available
+	###   memory. (See MDBX documentation for details.)
+	###
+	### [:no_threadlocal]
+	###   Parallelize read-only transactions across threads.  Writes are
+	###   always thread local. (See MDBX documentatoin for details.)
+	###
+	### [:no_readahead]
+	###   Disable all use of OS readahead.  Potentially useful for
+	###   random reads wunder low memory conditions.  Default behavior
+	###   is to dynamically choose when to use or omit readahead.
+	###
+	### [:no_memory_init]
+	###   Skip initializing malloc'ed memory to zeroes before writing.
+	###
+	### [:coalesce]
+	###   Attempt to coalesce items for the garbage collector,
+	###   potentialy increasing the chance of unallocating storage
+	###   earlier.
+	###
+	### [:lifo_reclaim]
+	###   Recycle garbage collected items via LIFO, instead of FIFO.
+	###   Depending on underlying hardware (disk write-back cache), this
+	###   could increase write performance.
+	###
+	### [:no_metasync]
+	###   A system crash may sacrifice the last commit for a potentially
+	###   large write performance increase.  Database integrity is
+	###   maintained.
+	###
 	def self::open( *args, &block )
 		db = new( *args )
 
@@ -40,7 +110,7 @@ class MDBX::Database
 	private_class_method :new
 
 
-	# The options used to instantiate this database.
+	# Options used when instantiating this database handle.
 	attr_reader :options
 
 	# The path on disk of the database.