lib/db_mod.rb in db_mod-0.0.5 vs lib/db_mod.rb in db_mod-0.0.6

@@ -9,29 +9,60 @@
 # This is the foundation module for enabling db_mod
 # support in an application. Including this module
 # will give your class or object the protected methods
 # {#db_connect} and {#conn=}, allowing the connection
 # to be set or created, as well as the methods {#conn},
-# {#query}, {#transaction}, and {#def_prepared}.
+# {#query}, {#transaction}, and +def_prepared+.
 module DbMod
   include Transaction
 
   # When a module includes {DbMod}, we define some
   # class-level functions specific to the module.
+  # This technique is required where it is not
+  # sufficient to simply define a module method
+  # on {DbMod} itself due to metaprogramming techniques
+  # requiring access to the module as +self+.
+  #
+  # See {DbMod::Create.setup}
+  # and {DbMod::Statements.setup}
+  #
+  # @param mod [Module] module which has had {DbMod} included
+  # @see http://ruby-doc.org/core-2.2.3/Module.html#method-i-included
+  #   Module#included
   def self.included(mod)
     DbMod::Create.setup(mod)
     DbMod::Statements.setup(mod)
+
+    # Ensure that these definitions cascade when
+    # submodules are included in subsequent submodules.
+    class << mod
+      define_method(:included) { |sub_mod| DbMod.included(sub_mod) }
+    end
   end
 
   protected
 
   # Database object to be used for all database
   # interactions in this module.
   # Use {#db_connect} to initialize the object.
-  attr_accessor :conn
+  #
+  # @return [PGconn] for now, only PostgreSQL is supported
+  attr_reader :conn
 
+  # A custom-built connection object
+  # may be supplied in place of calling {#db_connect}.
+  # Be aware in this case that certain responsibilities
+  # of {#db_connect} may need to be taken care of manually,
+  # in particular preparing SQL statements.
+  #
+  # @param value [PGconn] for now, only PostgreSQL is supported.
+  attr_writer :conn
+
   # Shorthand for +conn.query+
+  #
+  # @param sql [String] SQL query to execute
+  # @return [Object] SQL result set
   def query(sql)
     unless @conn
       fail DbMod::Exceptions::ConnectionNotSet, 'db_connect not called'
     end
     conn.query(sql)
@@ -63,19 +94,21 @@
   private
 
   # Load any missing options from defaults
   #
   # @param options [Hash] see {#db_connect}
+  # @see #db_connect
   def db_defaults!(options)
     fail ArgumentError, 'database name :db not supplied' unless options[:db]
     options[:port] ||= 5432
     options[:user] ||= ENV['USER']
     options[:pass] ||= 'trusted?'
   end
 
   # Create the database object itself.
   #
   # @param options [Hash] see {#db_connect}
+  # @return [PGconn] a new database connection
   def db_connect!(options)
     PGconn.connect(
       options[:host],
       options[:port],
       '',