Add/update documentation

.yardopts

@@ -1 +1,6 @@
 --exclude lib/super/test_support
+--exclude lib/generators
+--markup markdown
+-
+CONTRIBUTING.md
+LICENSE

README.md

@@ -18,19 +18,19 @@ your application's Rails version or any other gem.
 ## Features
 
 * Sprockets and Webpacker compatibility
-  * Note: Webpacker support depends on one additional NPM package for parsing
-    ERB
+    * Note: Webpacker support depends on one additional NPM package for parsing
+      ERB
 * Pagination
 * Configurable forms (new and edit forms)
 * Configurable display (index and show tables)
 * Supports Rails 5.0+, Ruby 2.3+
 * Configurable without a DSL
 * Looks reasonably nice and modern
 * Pre-built frontend assets (doesn't require Sass, PostCSS, Babel, etc)
-  * Vendored assets include
-    * Stimulus JS
-    * Tailwind CSS
-    * Feather icons
+    * Vendored assets include
+        * Stimulus JS
+        * Tailwind CSS
+        * Feather icons
 
 Super was inspired in part by the admin frameworks [ActiveAdmin][activeadmin]
 and [Administrate][administrate]. If Super doesn't quite fit your requirements
@@ -53,7 +53,7 @@ notified of its availability or for brief, occasional updates.
 ## Demos
 
 * [Super Demo][super_demo]
-  * [Super Demo source][super_demo_source]
+    * [Super Demo source][super_demo_source]
 * [Super Professional Demo][super_professional]
 
 

app/controllers/super/application_controller.rb

@@ -1,4 +1,5 @@
 module Super
+  # Provides a default implementation for each of the resourceful actions
   class ApplicationController < ActionController::Base
     include Super::InlineCallback
     include Pluggable.new(:super_application_controller)

lib/super/action_inquirer.rb

@@ -1,7 +1,20 @@
 module Super
+  # ```ruby
+  # action = Super::ActionInquirer.new(
+  #   Super::ActionInquirer.default_resources,
+  #   :index
+  # )
+  #
+  # action.read? # => true
+  # action.index? # => true
+  # action.show? # => false
+  # action.write? # => false
+  # ```
   class ActionInquirer
     attr_reader :action
 
+    # @return [Hash<Symbol, Array<Symbol>>] default settings for initialization
+    #
     def self.default_resources
       {
         read: %i[index show new edit],

lib/super/assets.rb

@@ -1,4 +1,5 @@
 module Super
+  # Utilities for determining whether to use Sprockets or Webpacker
   class Assets
     def self.sprockets_available?
       Gem::Dependency.new("sprockets").matching_specs.any?

lib/super/controls.rb

@@ -1,4 +1,7 @@
 module Super
+  # A wrapper around the per-controller Controls classes. This class often
+  # directly delegates to the per-controller classes, but it can also provide
+  # some default implementation.
   class Controls
     def initialize(actual)
       @actual = actual

lib/super/display/schema_types.rb

@@ -3,25 +3,24 @@ class Display
     # This schema type is meant to be used for +#index+ or +#show+ actions to
     # transform database fields into something that is human friendly.
     #
-    # Note: The constants under "Defined Under Namespace" are considered
-    # private.
+    # ```
+    # class MembersController::Controls
+    #   # ...
     #
-    #   class MemberDashboard
-    #     # ...
-    #
-    #     def show_schema
-    #       Super::Schema.new(Super::Display::SchemaTypes.new) do |fields, type|
-    #         fields[:name] = type.dynamic { |name| name }
-    #         fields[:rank] = type.dynamic { |rank| rank }
-    #         fields[:position] = type.dynamic { |position| position }
-    #         fields[:ship] = type.dynamic { |ship| "#{ship.name} (Ship ##{ship.id})" }
-    #         fields[:created_at] = type.dynamic { |created_at| created_at.iso8601 }
-    #         fields[:updated_at] = type.dynamic { |updated_at| updated_at.iso8601 }
-    #       end
+    #   def show_schema
+    #     Super::Schema.new(Super::Display::SchemaTypes.new) do |fields, type|
+    #       fields[:name] = type.dynamic { |name| name }
+    #       fields[:rank] = type.dynamic { |rank| rank }
+    #       fields[:position] = type.dynamic { |position| position }
+    #       fields[:ship] = type.dynamic { |ship| "#{ship.name} (Ship ##{ship.id})" }
+    #       fields[:created_at] = type.dynamic { |created_at| created_at.iso8601 }
+    #       fields[:updated_at] = type.dynamic { |updated_at| updated_at.iso8601 }
     #     end
-    #
-    #     # ...
     #   end
+    #
+    #   # ...
+    # end
+    # ```
     class SchemaTypes
       class Dynamic
         def initialize(transform_block)

lib/super/engine.rb

@@ -1,4 +1,5 @@
 module Super
+  # Configures the host Rails app to work with Super
   class Engine < ::Rails::Engine
     initializer "super.assets.precompile" do |app|
       if Super::Assets.sprockets_available?

lib/super/error.rb

@@ -1,4 +1,5 @@
 module Super
+  # A container class for all custom errors thrown by this library
   class Error < StandardError
     class UnconfiguredConfiguration < Error; end
     class InvalidConfiguration < Error; end

lib/super/form/schema_types.rb

@@ -2,26 +2,25 @@ module Super
   class Form
     # This schema type is used on your +#edit+ and +#new+ forms
     #
-    # Note: The constants under "Defined Under Namespace" are considered
-    # private.
+    # ```ruby
+    # class MembersController::Controls
+    #   # ...
     #
-    #   class MemberDashboard
-    #     # ...
-    #
-    #     def new_schema
-    #       Super::Schema.new(Super::Form::SchemaTypes.new) do |fields, type|
-    #         fields[:name] = type.generic("form_field_text")
-    #         fields[:rank] = type.generic("form_field_select", collection: Member.ranks.keys)
-    #         fields[:position] = type.generic("form_field_text")
-    #         fields[:ship_id] = type.generic(
-    #           "form_field_select",
-    #           collection: Ship.all.map { |s| ["#{s.name} (Ship ##{s.id})", s.id] },
-    #         )
-    #       end
+    #   def new_schema
+    #     Super::Schema.new(Super::Form::SchemaTypes.new) do |fields, type|
+    #       fields[:name] = type.generic("form_field_text")
+    #       fields[:rank] = type.generic("form_field_select", collection: Member.ranks.keys)
+    #       fields[:position] = type.generic("form_field_text")
+    #       fields[:ship_id] = type.generic(
+    #         "form_field_select",
+    #         collection: Ship.all.map { |s| ["#{s.name} (Ship ##{s.id})", s.id] },
+    #       )
     #     end
-    #
-    #     # ...
     #   end
+    #
+    #   # ...
+    # end
+    # ```
     class SchemaTypes
       class Generic
         def initialize(partial_path:, extras:, nested:)
@@ -32,10 +31,12 @@ def initialize(partial_path:, extras:, nested:)
 
         attr_reader :nested_fields
 
+        # This takes advantage of a feature of Rails. If the value of
+        # `#to_partial_path` is `my_form_field`, Rails renders
+        # `app/views/super/application/_my_form_field.html.erb`, and this
+        # instance of Generic is accessible via `my_form_field`
+        #
         # @return [String] the filename of the partial that will be rendered.
-        #  If the value of `#to_partial_path` is `my_form_field`, Rails will
-        #  render `app/views/super/application/_my_form_field.html.erb`, and
-        #  this instance of Generic is accessible via `my_form_field`
         def to_partial_path
           @partial_path
         end

lib/super/navigation/automatic.rb

@@ -1,5 +1,7 @@
 module Super
   class Navigation
+    # Traverses the defined Rails Routes and attempts to build a list of links.
+    # This is used for building the nav bar on each admin page.
     class Automatic
       def initialize(route_namespace:)
         route_namespace = route_namespace.to_s