brut 0.0.1 → 0.0.2

data/lib/brut/spec_support/handler_support.rb

@@ -1,7 +1,9 @@
 require_relative "flash_support"
+require_relative "clock_support"
 require_relative "session_support"
 module Brut::SpecSupport::HandlerSupport
   include Brut::SpecSupport::FlashSupport
+  include Brut::SpecSupport::ClockSupport
   include Brut::SpecSupport::SessionSupport
 end
 

data/lib/brut/spec_support/matcher.rb

@@ -1,9 +1,12 @@
 module Brut::SpecSupport::Matchers
 end
+require_relative "matchers/be_a_bug"
+require_relative "matchers/be_page_for"
+require_relative "matchers/be_routing_for"
 require_relative "matchers/have_constraint_violation"
 require_relative "matchers/have_html_attribute"
-require_relative "matchers/be_routing_for"
-require_relative "matchers/be_page_for"
+require_relative "matchers/have_i18n_string"
+require_relative "matchers/have_redirected_to"
 require_relative "matchers/have_rendered"
 require_relative "matchers/have_returned_http_status"
-require_relative "matchers/be_a_bug"
+require_relative "matchers/have_link_to"

data/lib/brut/spec_support/matchers/be_page_for.rb

@@ -6,9 +6,10 @@ RSpec::Matchers.define :be_page_for do |klass|
   failure_message do |page|
     meta = page.locator("meta[name='class']")
     if meta.count == 0
-      "Could not find <meta name='class'> on the page:\n\n#{page.content}"
+      "Could not find <meta name='class'> on the page, which is what's needed to know what page we are on:\n\n#{page.content}"
     else
-      "Could not find <meta name='class' content='#{klass.name}'>, but found:\n\n#{meta.evaluate('e => e.outerHTML')}"
+      page_name = meta.get_attribute("content")
+      "Expected to be on page #{klass.name}, but we seem to be on page #{page_name}, based on this meta tag:\n\n#{meta.evaluate('e => e.outerHTML')}"
     end
   end
 end

data/lib/brut/spec_support/matchers/have_constraint_violation.rb

@@ -1,14 +1,26 @@
-RSpec::Matchers.define :have_constraint_violation do |field,key:|
+RSpec::Matchers.define :have_constraint_violation do |field,key:,index:nil|
   match do |form|
-    Brut::SpecSupport::Matchers::HaveConstraintViolation.new(form,field,key).matches?
+    Brut::SpecSupport::Matchers::HaveConstraintViolation.new(form,field,key,index).matches?
   end
 
   failure_message do |form|
-    analysis = Brut::SpecSupport::Matchers::HaveConstraintViolation.new(form,field,key)
+    analysis = Brut::SpecSupport::Matchers::HaveConstraintViolation.new(form,field,key,index)
     if analysis.found_field?
-      "#{field} did not have #{key} as a violation.  These keys were found: #{analysis.keys_on_field_found.map(&:to_s).join(", ")}"
+      "Field '#{field}' did not have key '#{key}' as a violation.  These keys were found: #{analysis.keys_on_field_found.map(&:to_s).join(", ")}"
     else
-      "#{field} had no errors.  These fields DID: #{analysis.fields_found.map(&:to_s).join(", ")}"
+      field_searched_for = if index.nil?
+                             field
+                           else
+                             "#{field}, index #{index}"
+                           end
+      fields_with_errors = analysis.fields_found.map { |(field,index)|
+        if index.nil?
+          field
+        else
+          "#{field}, index #{index}"
+        end
+      }.join(", ")
+      "Field '#{field_searched_for}' had no errors.  These fields DID: #{fields_with_errors}"
     end
   end
 
@@ -21,21 +33,22 @@ class Brut::SpecSupport::Matchers::HaveConstraintViolation
   attr_reader :fields_found
   attr_reader :keys_on_field_found
 
-  def initialize(form, field, key)
+  def initialize(form, field, key, index)
     if !form.kind_of?(Brut::FrontEnd::Form)
       raise "#{self.class} only works with forms, not #{form.class}"
     end
     @form  = form
     @field = field.to_s
     @key   = key.to_s
+    @index = index || 0
 
     @matches             = false
     @found_field         = false
     @fields_found        = Set.new
     @keys_on_field_found = Set.new
 
-    @form.constraint_violations.each do |input_name, constraint_violations|
-      if input_name.to_s == @field
+    @form.constraint_violations.each do |input_name, (constraint_violations, index)|
+      if input_name.to_s == @field && index == @index
         @found_field = true
         constraint_violations.each do |constraint_violation|
           if constraint_violation.key.to_s == @key
@@ -45,7 +58,7 @@ class Brut::SpecSupport::Matchers::HaveConstraintViolation
           end
         end
       else
-        @fields_found << input_name.to_s
+        @fields_found << [ input_name.to_s, index ]
       end
     end
   end

data/lib/brut/spec_support/matchers/have_html_attribute.rb

@@ -38,8 +38,15 @@ class Brut::SpecSupport::Matchers::HaveHTMLAttribute
       else
         result = result.first
       end
-    elsif (!result.kind_of?(Nokogiri::XML::Element))
-      @error = "Received a #{result.class} instead of a NodeSet or Element, as could be returned by `.css(...)`"
+    else
+      object_to_check = if result.kind_of?(SimpleDelegator)
+                          result.__getobj__
+                        else
+                          result
+                        end
+      if !object_to_check.kind_of?(Nokogiri::XML::Element)
+        @error = "Received a #{result.class} instead of a NodeSet or Element, as could be returned by `.css(...)`"
+      end
     end
     if !@error
       if attribute.kind_of?(Hash)

data/lib/brut/spec_support/matchers/have_i18n_string.rb

@@ -0,0 +1,24 @@
+RSpec::Matchers.define :have_i18n_string do |key,**args|
+  include Brut::I18n::ForHTML
+  match do |nokogiri_node|
+
+    text        = nokogiri_node.text.strip
+    i18n_string = t(key,**args).to_s
+
+    text == i18n_string
+  end
+
+  failure_message do |nokogiri_node|
+    text = nokogiri_node.text.strip
+    begin
+      "Expected '#{text}' to be '#{t(key,**args)}'\n#{nokogiri_node.to_html}\n"
+    rescue => ex
+      "I18n key '#{key}' could not be found: #{ex.message}"
+    end
+  end
+
+  failure_message_when_negated do |nokogiri_node|
+    "Did not expect node's text to be '#{t(key,**args)}'\n#{nokogiri_node.to_html}\n"
+  end
+end
+

data/lib/brut/spec_support/matchers/have_link_to.rb

@@ -0,0 +1,14 @@
+RSpec::Matchers.define :have_link_to do |page_klass,**args|
+  match do |node|
+    node.css("a[href='#{page_klass.routing(**args)}']").any?
+  end
+
+  failure_message do |node|
+    links = node.css("a").map(&:to_html)
+    "Did not find link to #{page_klass.routing(**args)}. Found these links: #{links.join(',')}"
+  end
+
+  failure_message_when_negated do |result|
+    "Did not expect to find link to #{page_klass.routing(**args)}."
+  end
+end

data/lib/brut/spec_support/matchers/have_redirected_to.rb

@@ -0,0 +1,30 @@
+RSpec::Matchers.define :have_redirected_to do |page_or_uri,**page_params|
+  match do |result|
+    if page_or_uri.kind_of?(URI)
+      if !page_params.empty?
+        raise "have_redirected_to, when given a URI, must NOT be given parameters. Got  '#{page_params}'"
+      end
+      result == page_or_uri
+    elsif page_or_uri.ancestors.include?(Brut::FrontEnd::Page)
+      result == page_or_uri.routing(**page_params)
+    else
+      raise "have_redirected_to must be given a URI or a Brut::FrontEnd::Page class, got #{page_or_uri.class}"
+    end
+  rescue Brut::Framework::Errors::MissingParameter => ex
+    raise "#{page_or_uri}'s routing requires parameters you must specicfy to `have_redirected_to`: #{ex.message}"
+  end
+
+  failure_message do |result|
+    if page_or_uri.kind_of?(URI)
+      "Expected #{page_or_uri} but got #{result}"
+    elsif page_or_uri.ancestors.include?(Brut::FrontEnd::Page)
+      "Expected #{page_or_uri}'s routing (#{page_or_uri.routing(**page_params)}), but got #{result}"
+    else
+      "Unknown error occured or bug with have_redirected_to"
+    end
+  end
+  failure_message_when_negated do |result|
+    "Got a redirect when it wasn't expected"
+  end
+
+end

data/lib/brut/spec_support/matchers/have_rendered.rb

@@ -1,20 +1,13 @@
-RSpec::Matchers.define :have_rendered do
+RSpec::Matchers.define :have_rendered do |component_or_page|
   match do |result|
-    result.kind_of?(String) || result.kind_of?(Brut::FrontEnd::Templates::HTMLSafeString)
+    result.class.ancestors.include?(component_or_page)
   end
 
   failure_message do |result|
-    case result
-    in URI => uri
-      "Got a redirect to #{uri} instead of rendering"
-    in Brut::FrontEnd::HttpStatus => http_status
-      "Got an HTTP status of #{http_status} instead of rendering"
-    else
-      "Got an unexpected result: #{result.class} instead of a String"
-    end
+    "Expected a #{component_or_page} to be rendered, but got #{result}"
   end
   failure_message_when_negated do |result|
-    "Result was rendered HTML instead of something else"
+    "Got #{component_or_page} when not expected"
   end
 
 end

data/lib/brut/spec_support/matchers/have_returned_http_status.rb

@@ -1,12 +1,16 @@
-RSpec::Matchers.define :have_returned_http_status do |http_status|
+RSpec::Matchers.define :have_returned_http_status do |http_status=nil|
   match do |result|
-    case result
-    in URI => uri
-      http_status == 302
-    in Brut::FrontEnd::HttpStatus => result_http_status
-      http_status == result_http_status.to_i
+    if http_status.nil?
+      result.kind_of?(Brut::FrontEnd::HttpStatus)
     else
-      http_status == 200
+      case result
+      in URI => uri
+        http_status == 302
+      in Brut::FrontEnd::HttpStatus => result_http_status
+        http_status == result_http_status.to_i
+      else
+        http_status == 200
+      end
     end
   end
 
@@ -21,7 +25,11 @@ RSpec::Matchers.define :have_returned_http_status do |http_status|
     end
   end
   failure_message_when_negated do |result|
-    "Result was rendered HTML instead of something else"
+    if http_status.nil?
+      "#{result} was rendered, but was not expecting an HTTP status"
+    else
+      "Got #{http_status} when not expected (#{result.class} was returned)"
+    end
   end
 
 end

data/lib/brut/spec_support/rspec_setup.rb

@@ -0,0 +1,182 @@
+# Configures RSpec for Brut.  This provides several bits of infrastructure only present when the app is running, as well as
+# quality of life improvements to make testing Brut components a bit easier.  Even though Brut classes are all normal classes, it's
+# convenient to have extraneous classes set up for you.
+#
+# * Metadata is added based on the class names under test:
+#   - `*Component` -> `:component`
+#   - `*Page` -> `:component`
+#   - `*Page` -> `:page`
+#   - `*Handler` -> `:handler`
+#   - If you add the `:page` metadata automatically, `:component` is added as well.
+#   - Tests in `specs/e2e` or any subfolder -> `:e2e`
+#   - Note that you are free to explicitly add these tags to your test metadata. That will cause the inclusion of modules as described below
+# * Modules are included to provide additional support for writing tests:
+#   - {Brut::SpecSupport::GeneralSupport} included in all tests
+#   - {Brut::SpecSupport::ComponentSupport} included when `:component` metadata is set (generally, this is for page and component tests)
+#   - {Brut::SpecSupport::HandlerSupport} included when `:handler` is set.
+#   - {Playwright::Test::Matchers{ included when `:e2e` is set, which allows use of the Ruby binding for Playwright.
+# * Non end-to-end tests will be run inside a database transaction to allow all database changes to be instantly undone.  This does
+# mean that any tests that tests database transaction behavior will not work as expected.
+# * In component tests (which generally includes page tests), a {Brut::FrontEnd::RequestContext} is created for you and placed into
+# the thread local storage.  This allows any component that is injected with data from the `RequestContext` to access it as it would
+# normally.  You can also seed this with data that a component may need.
+# * Handles all infrastructure for end-to-end tests:
+#   - starting a test server using {Brut::SpecSupport::E2ETestServer}
+#   - launching Chromium via Playwright
+# * If using Sidekiq:
+#   - Jobs are cleared before each test
+#   - For end-to-end tests, Redis is flushed and actual Sidekiq is used instead of testing mode
+#
+# You can set certain metadata to change behavior:
+#
+# * `e2e_timeout` - number of milliseconds to wait until an end-to-end test gives up on a selector being found.  The default is 5,000 (5 seconds). Use this only if there's no other way to keep your test from needing more than 5 seconds.
+#
+#
+# @example
+#     RSpec.configure do |config|
+#       rspec_setup = Brut::SpecSupport::RSpecSetup.new(rspec_config: config)
+#       rspec_setup.setup!
+#
+#       # rest of the RSpec configuration
+#     end
+class Brut::SpecSupport::RSpecSetup
+  # Create the setup with the given RSpec configuration.
+  #
+  # @param [RSpec::Core::Configuration] rspec_config yielded from `RSpec.configure`
+  def initialize(rspec_config:)
+    @config = rspec_config
+    SemanticLogger.default_level = ENV.fetch("LOGGER_LEVEL_FOR_TESTS","warn")
+  end
+
+  # Sets up RSpec with variouis configurations needed by Brut to run your tests.
+  #
+  # @param [Proc] inside_db_transaction if given, this is run inside the DB transaction before your example is run. This is useful if you need to set up some reference data for all tests.
+  def setup!(inside_db_transaction: ->() {})
+
+    Brut::FactoryBot.new.setup!
+    optional_sidekiq_support = OptionalSidekiqSupport.new
+
+    @config.define_derived_metadata do |metadata|
+      if metadata[:described_class].to_s =~ /[a-z0-9]Component$/ ||
+          metadata[:described_class].to_s =~ /[a-z0-9]Page$/ ||
+          metadata[:page] == true
+        metadata[:component] = true
+      end
+      if metadata[:described_class].to_s =~ /[a-z0-9]Page$/ ||
+          metadata[:page] == true
+        metadata[:page] = true
+      end
+      if metadata[:described_class].to_s =~ /[a-z0-9]Handler$/
+        metadata[:handler] = true
+      end
+
+      relative_path = Pathname(metadata[:absolute_file_path]).relative_path_from(Brut.container.app_specs_dir)
+
+      top_level_directory = relative_path.each_filename.to_a[0].to_s
+      if top_level_directory == "e2e"
+        metadata[:e2e] = true
+      end
+    end
+    @config.include Brut::SpecSupport::GeneralSupport
+    @config.include Brut::SpecSupport::ComponentSupport, component: true
+    @config.include Brut::SpecSupport::HandlerSupport, handler: true
+    @config.include Playwright::Test::Matchers, e2e: true
+
+    @config.around do |example|
+
+      needs_request_context = example.metadata[:component] ||
+                              example.metadata[:handler]   ||
+                              example.metadata[:page]
+
+      if needs_request_context
+        session = {
+          "session_id" => "test-session-id",
+          "csrf" => "test-csrf-token"
+        }
+        env = {
+          "rack.session" => session
+        }
+        app_session = Brut.container.session_class.new(rack_session: session)
+        request_context = Brut::FrontEnd::RequestContext.new(
+          env: env,
+          session: app_session,
+          flash: empty_flash,
+          body: nil,
+          xhr: false,
+        )
+        Thread.current.thread_variable_set(:request_context, request_context)
+        example.example_group.let(:request_context) { request_context }
+      end
+      if example.metadata[:component]
+        example.example_group.let(:component_name) { described_class.component_name }
+      end
+      if example.metadata[:page]
+        example.example_group.let(:page_name) { described_class.page_name }
+      end
+
+      if example.metadata[:e2e]
+        e2e_timeout = (ENV["E2E_TIMEOUT_MS"] || example.metadata[:e2e_timeout] || 5_000).to_i
+        optional_sidekiq_support.disable_sidekiq_testing do
+          Brut::SpecSupport::E2ETestServer.instance.start
+          Playwright.create(playwright_cli_executable_path: "./node_modules/.bin/playwright") do |playwright|
+            launch_args = {
+              headless: true,
+            }
+            if ENV["E2E_SLOW_MO"]
+              launch_args[:slowMo] = ENV["E2E_SLOW_MO"].to_i
+            end
+            playwright.chromium.launch(**launch_args) do |browser|
+              context_options = {
+                baseURL: "http://0.0.0.0:6503/",
+              }
+              if ENV["E2E_RECORD_VIDEOS"]
+                context_options[:record_video_dir] = Brut.container.tmp_dir / "e2e-videos"
+              end
+              browser_context = browser.new_context(**context_options)
+              browser_context.default_timeout = e2e_timeout
+              example.example_group.let(:page) { browser_context.new_page }
+              example.run
+              browser_context.close
+              browser.close
+            end
+          end
+        end
+      else
+        optional_sidekiq_support.clear_background_jobs
+        Sequel::Model.db.transaction do
+          inside_db_transaction.()
+          example.run
+          raise Sequel::Rollback
+        end
+      end
+    end
+    @config.after(:suite) do
+      Brut::SpecSupport::E2ETestServer.instance.stop
+    end
+  end
+
+  class OptionalSidekiqSupport
+    def initialize
+      @sidekiq_in_use = defined?(Sidekiq)
+    end
+
+    def disable_sidekiq_testing(&block)
+      if @sidekiq_in_use
+        Sidekiq::Testing.disable! do
+          Sidekiq.redis do |redis|
+            redis.flushall
+          end
+          block.()
+        end
+      else
+        block.()
+      end
+    end
+    def clear_background_jobs
+      if @sidekiq_in_use
+        Sidekiq::Worker.clear_all
+      end
+    end
+  end
+
+end

data/lib/brut/spec_support.rb

@@ -1,7 +1,7 @@
-# Convention here is different. We don't want to autoload
-# a lot of stuff, since RSpec pollutes the Object namespace.
-# Instead, we'll require that these files are required explicitly
 module Brut
+  # Spec Support holds various matchers and helpers useful when writing tests with RSpec.
+  # Note that this module and it's contents aren't loaded by default when you `require "brut"`.
+  # Your app's `spec_helper.rb` should require these properly.
   module SpecSupport
   end
 end
@@ -9,4 +9,9 @@ require_relative "spec_support/matcher"
 require_relative "spec_support/component_support"
 require_relative "spec_support/handler_support"
 require_relative "spec_support/general_support"
+require_relative "spec_support/e2e_test_server"
+require_relative "spec_support/rspec_setup"
 require_relative "factory_bot"
+# Convention here is different. We don't want to autoload
+# a lot of stuff, since RSpec pollutes the Object namespace.
+# Instead, we'll require that these files are required explicitly

data/lib/brut/version.rb

@@ -1,3 +1,4 @@
 module Brut
-  VERSION = "0.0.1"
+  # @!visibility private
+  VERSION = "0.0.2"
 end

data/lib/brut.rb

@@ -1,10 +1,29 @@
 require_relative "brut/framework"
 
-# Convention is as follows:
+# Brut is a way to make web apps with Ruby. It focuses on web standards, object-orientation, and other fundamentals. Brut seeks to
+# minimize abstractions where possible.
 #
-# * singluar thing is a class, the base class of others  being used, e.g. the base page is called Brut::Page
-#   (e.g. and not Brut::Pages::Base).
+# Brut encourages the use of the browser's technology and encourages you to build a web app based on good practices that are set up by
+# default.  Brut may not look easy, but it aims to be simple.  It attempts to minimize dependencies and complexity, while leveraging
+# common tested Ruby libraries related to web development.
+#
+# Have fun!
 module Brut
+  # In Brut, the _front end_ is considered anything that interacts directly with a web browser or HTTP.  This includes rendering HTML,
+  # managing JavaScript and CSS, and processing form submissions.  It contrasts to {Brut::BackEnd}, which handles the business logic
+  # and database.
+  #
+  # You {Brut::App} defines pages, forms, and actions. A page is backed by a subclass of {Brut::FrontEnd::Page}, which provides
+  # dynamic data for rendering. A page can reference {Brut::FrontEnd::Component} subclasses to allow functional decomposition of front
+  # end logic and markup, as well as re-use.  Both pages and components have ERB files that describe the HTML to be rendered.
+  #
+  # A {Brut::FrontEnd::Form} subclass defines a form that a browser will submit to your app. That
+  # submission is processed by a {Brut::FrontEnd::Handler} subclass.  Handlers can also respond to other HTTP requests.
+  #
+  # In addition to responding to requests, you can subclass {Brut::FrontEnd::RouteHook} or {Brut::FrontEnd::Middleware} to perform
+  # further manipulation of the request.
+  #
+  # The entire front-end is based on Rack, so you should be able to achieve anything you need to.
   module FrontEnd
     autoload(:AssetMetadata, "brut/front_end/asset_metadata")
     autoload(:Component, "brut/front_end/component")
@@ -20,19 +39,23 @@ module Brut
     autoload(:Middleware, "brut/front_end/middleware")
     autoload(:Middlewares, "brut/front_end/middleware")
     autoload(:Page, "brut/front_end/page")
+    autoload(:Pages, "brut/front_end/page")
     autoload(:RequestContext, "brut/front_end/request_context")
     autoload(:RouteHook, "brut/front_end/route_hook")
     autoload(:RouteHooks, "brut/front_end/route_hook")
     autoload(:Routing, "brut/front_end/routing")
     autoload(:Session, "brut/front_end/session")
   end
+  # The _back end_ of a Brut app is where your app's business logic and database are managed.  While the bulk of your Brut app's code
+  # will be in the back end, Brut is far less prescriptive about how to manage that than it is the front end.
   module BackEnd
-    autoload(:Result, "brut/back_end/result")
     autoload(:Validators, "brut/back_end/validator")
+    # Do not put SeedData here - it must be loaded only when needed
   end
-  # DO NOT autoload(:CLI) - that is intended to be require-able on its own
+  # I18n is where internationalization and localization support lives.
   autoload(:I18n, "brut/i18n")
   autoload(:Instrumentation,"brut/instrumentation")
   autoload(:SinatraHelpers, "brut/sinatra_helpers")
+  # DO NOT autoload(:CLI) - that is intended to be require-able on its own
 end
 require "sequel/plugins"

data/lib/sequel/extensions/brut_instrumentation.rb

@@ -1,37 +1,15 @@
 module Sequel
   module Extensions
+    # Instruments all SQL executions.
     module BrutInstrumentation
-      class Event < Brut::Instrumentation::Event
-        def initialize(operation:,sql:nil)
-          super(category: "sequel", name: operation, details: { sql: sql })
-        end
-      end
-      def execute(sql, opts = Sequel::OPTS, &block)
-        Brut.container.instrumentation.instrument(Event.new(operation: "execute", sql: sql)) do
-          super
-        end
-      end
-      def execute_dui(sql, opts = Sequel::OPTS, &block)
-        Brut.container.instrumentation.instrument(Event.new(operation: "execute_dui", sql: sql)) do
-          super
-        end
-      end
-      def execute_insert(sql, opts = Sequel::OPTS, &block)
-        Brut.container.instrumentation.instrument(Event.new(operation: "execute_insert", sql: sql)) do
-          super
-        end
-      end
-      def insert_select(*values)
-        Brut.container.instrumentation.instrument(Event.new(operation: "insert_select", sql: values)) do
-          super
-        end
-      end
-      def returning_fetch_rows(sql,&block)
-        Brut.container.instrumentation.instrument(Event.new(operation: "returning_fetch_rows", sql: sql)) do
+      # @!visibility private
+      def log_connection_yield(sql,conn,args=nil)
+        Brut.container.instrumentation.span("SQL", sql: sql) do |span|
           super
         end
       end
     end
   end
   Sequel::Dataset.register_extension(:brut_instrumentation, Sequel::Extensions::BrutInstrumentation)
+  Sequel::Database.register_extension(:brut_instrumentation, Sequel::Extensions::BrutInstrumentation)
 end

data/lib/sequel/extensions/brut_migrations.rb

@@ -1,15 +1,20 @@
 module Sequel
   module Extensions
-    # Enhancements to migrations to encourage better practices and reduce boilerplate.
+    # Modifies and enhances Sequel's migrations DSL to default to best practices.
     #
-    # * If no primary key is specified, a primary key column named :id of type :int will be created
-    # * If no created_at is specified, a column name created_at of type timestamptz is created
-    # * create_table requires a comment: field
-    # * create_table accepts an external_id: true option that will create a unique citext called "external_id"
-    # * columns are non-null by default
-    # * foreign keys are non-null and an index is created
-    # * the `key` method allows specifying keys aka creating a unique constraint
+    # * If no primary key is specified, a primary key column named `id` of type `int` will be created.
+    # * If no `created_at` is specified, a column name `created_at` of type `timestamptz` is created.
+    # * `create_table` requires a `comment:` attribute that explains the purpose of the table.
+    # * `create_table` accepts an `external_id: true` attribute that will create a unique `citext` field named `external_id`. This is intended to be used with {Sequel::Plugins::ExternalId}.
+    # * Columns are non-null by default. To make a nullable column, use `null: true`.
+    # * Foreign keys are non-null by default and an index is created by default.
+    # * The `key` method allows specifying additional keys on the table. This effecitvely creates a unique constraint on the fields given to `key`.
     module BrutMigrations
+      # Overrides Sequel's `create_table`
+      #
+      # @param args [Object] the arguments to pass to Sequel's `create_table`.  If the last entry in `*args` is a `Hash`, new options are recognized:
+      # @option args [String] :comment String containing the table's description, included in the table definition. Required.
+      # @option args [true|false] :external_id If true, adds a `:citext` column named `external_id` that has a unique index on it.
       def create_table(*args)
         super
 
@@ -27,10 +32,15 @@ module Sequel
         end
       end
 
+      # Specifies a non-primary key based on the fields given. Effectively creates a unique index on these fields.
+      # Inside a `create_table` block, this can be called via `key`
+      #
+      # @param fields [Array] fields that should form the key.
       def add_key(fields)
         add_index fields, unique: true
       end
 
+      # Overrides Sequel's `add_column` to default `null: false`.
       def add_column(table,*args)
         options = args.last
         if options.is_a?(Hash)

data/lib/sequel/plugins/created_at.rb

@@ -1,7 +1,9 @@
 module Sequel
   module Plugins
+    # Automatically sets `created_at` on all models.
     module CreatedAt
       module InstanceMethods
+        # @!visibility private
         def before_save
           if self.created_at.nil?
             self.created_at = Time.now