hanami 1.0.0.beta2 → 1.0.0.beta3

data/lib/hanami/config/sessions.rb

@@ -2,6 +2,8 @@ require 'ipaddr'
 require 'hanami/utils/string'
 
 module Hanami
+  # @since 0.2.0
+  # @api private
   module Config
     # Sessions configuration
     #
@@ -82,6 +84,8 @@ module Hanami
         end
       end
 
+      # @since 0.2.0
+      # @api private
       def domain
         domain = @configuration.host
         if !BLACKLISTED_DOMAINS.include?(domain) && !ip_address?(domain)
@@ -89,6 +93,8 @@ module Hanami
         end
       end
 
+      # @since 0.2.0
+      # @api private
       def ip_address?(string)
         !!IPAddr.new(string) rescue false
       end

data/lib/hanami/configuration.rb

@@ -5,25 +5,65 @@ require 'hanami/utils/class'
 require 'hanami/utils/string'
 
 module Hanami
+  # @api private
   class Configuration
+    # @api private
     class App < SimpleDelegator
+      # @api private
       attr_reader :path_prefix
 
+      # @api private
       def initialize(app, path_prefix)
         super(app)
         @path_prefix = path_prefix
       end
     end
 
+    # @api private
     def initialize(&blk)
       @settings = Concurrent::Map.new
       instance_eval(&blk)
     end
 
+    # Mount a Hanami::Application or a Rack app
+    #
+    # @param app [#call] an application compatible with Rack SPEC
+    # @param options [Hash] a set of options
+    # @option :at [String] options the mount point
+    #
+    # @since 0.9.0
+    #
+    # @example
+    #   # config/environment.rb
+    #   # ...
+    #   Hanami.configure do
+    #     mount Web::Application, at: '/'
+    #
+    #     # ...
+    #   end
     def mount(app, options)
       mounted[app] = App.new(app, options.fetch(:at))
     end
 
+    # Configure database
+    #
+    # @param blk [Proc] the database configuration
+    #
+    # @see Hanami::Model.configure
+    #
+    # @example
+    #   # config/environment.rb
+    #   # ...
+    #   Hanami.configure do
+    #     model do
+    #       adapter :sql, ENV['DATABASE_URL']
+    #
+    #       migrations 'db/migrations'
+    #       schema     'db/schema.sql'
+    #     end
+    #
+    #     # ...
+    #   end
     def model(&blk)
       if block_given?
         settings.put_if_absent(:model, blk)
@@ -32,20 +72,61 @@ module Hanami
       end
     end
 
+    # Configure mailer
+    #
+    # @param blk [Proc] the mailer configuration
+    #
+    # @see Hanami::Mailer.configure
+    #
+    # @example
+    #   # config/environment.rb
+    #   # ...
+    #   Hanami.configure do
+    #     mailer do
+    #       root 'lib/bookshelf/mailers'
+    #
+    #       # See http://hanamirb.org/guides/mailers/delivery
+    #       delivery :test
+    #     end
+    #
+    #     # ...
+    #   end
     def mailer(&blk)
       settings.put_if_absent(:mailer, blk)
     end
 
+    # @since 0.9.0
+    # @api private
     def mounted
       settings.fetch_or_store(:mounted, {})
     end
 
+    # @since 0.9.0
+    # @api private
     def apps
       mounted.each_pair do |klass, app|
         yield(app) if klass.ancestors.include?(Hanami::Application)
       end
     end
 
+    # Configure logger
+    #
+    # @since 1.0.0.beta1
+    #
+    # @param options [Hash] a set of options
+    #
+    # @see Hanami.logger
+    # @see Hanami::Logger
+    #
+    # @example
+    #   # config/environment.rb
+    #   # ...
+    #   Hanami.configure do
+    #     # ...
+    #     environment :development do
+    #       logger level: :debug
+    #     end
+    #   end
     def logger(options = nil)
       if options.nil?
         settings.fetch(:logger, nil)
@@ -54,12 +135,33 @@ module Hanami
       end
     end
 
+    # Configure settings for the current environment
+    # @since 1.0.0.beta1
+    #
+    # @param name [Symbol] the name of the Hanami environment
+    #
+    # @see Hanami.env
+    #
+    # @example Configure Logging for Different Environments
+    #   # config/environment.rb
+    #   # ...
+    #   Hanami.configure do
+    #     # ...
+    #     environment :development do
+    #       logger level: :debug
+    #     end
+    #
+    #     environment :production do
+    #       logger level: :info, formatter: :json
+    #     end
+    #   end
     def environment(name)
       yield if ENV['HANAMI_ENV'] == name.to_s
     end
 
     private
 
+    # @api private
     attr_reader :settings
   end
 end

data/lib/hanami/environment.rb

@@ -157,6 +157,8 @@ module Hanami
     # @see Hanami::Commands::Server
     # @see Hanami::Environment#config
     #
+    # @api private
+    #
     # @example Define ENV variables from .env
     #
     #   # % tree .
@@ -219,6 +221,7 @@ module Hanami
     # @return [String] the current environment
     #
     # @since 0.1.0
+    # @api private
     #
     # @see Hanami::Environment::DEFAULT_ENV
     def environment
@@ -226,6 +229,7 @@ module Hanami
     end
 
     # @since 0.3.1
+    # @api private
     #
     # @see Hanami.env?(name)
     def environment?(*names)
@@ -262,6 +266,7 @@ module Hanami
     # @return [Pathname] application's root
     #
     # @since 0.2.0
+    # @api private
     def root
       @root ||= Pathname.new(Dir.pwd)
     end
@@ -282,6 +287,7 @@ module Hanami
     # @return [Pathname] the config directory
     #
     # @since 0.2.0
+    # @api private
     #
     # @see Hanami::Environment::DEFAULT_CONFIG
     # @see Hanami::Environment#root
@@ -304,6 +310,7 @@ module Hanami
     # @return [String] the HTTP host name
     #
     # @since 0.1.0
+    # @api private
     #
     # @see Hanami::Environment::DEFAULT_HOST
     # @see Hanami::Environment::LISTEN_ALL_HOST
@@ -325,6 +332,7 @@ module Hanami
     # @return [Integer] the default port
     #
     # @since 0.1.0
+    # @api private
     #
     # @see Hanami::Environment::DEFAULT_PORT
     def port
@@ -357,6 +365,7 @@ module Hanami
     # @return [Pathname] path to the Rack configuration file
     #
     # @since 0.2.0
+    # @api private
     def rackup
       root.join(@options.fetch(:rackup) { DEFAULT_RACKUP })
     end
@@ -376,6 +385,7 @@ module Hanami
     # @return [Pathname] path to applications
     #
     # @since 0.1.0
+    # @api private
     #
     # @see Hanami::Environment::DEFAULT_ENVIRONMENT_CONFIG
     def env_config
@@ -394,6 +404,7 @@ module Hanami
       require project_environment_configuration.to_s # if project_environment_configuration.exist?
     end
 
+    # @api private
     alias require_project_environment require_application_environment
 
     # Determine if activate code reloading for the current environment while
@@ -411,6 +422,7 @@ module Hanami
     # @return [TrueClass,FalseClass] the result of the check
     #
     # @since 0.2.0
+    # @api private
     #
     # @see Hanami::Commands::Server
     # @see Hanami::Environment::CODE_RELOADING
@@ -483,6 +495,7 @@ module Hanami
 
     private
 
+    # @api private
     attr_reader :env
 
     # @since 0.1.0

data/lib/hanami/environment_application_configurations.rb

@@ -1,16 +1,21 @@
 module Hanami
+  # @api private
   class EnvironmentApplicationConfigurations
+    # @api private
     ALL = :all
 
+    # @api private
     def initialize
       @configurations = Concurrent::Hash.new { |k, v| k[v] = [] }
     end
 
+    # @api private
     def add(environment, &blk)
       env = (environment || ALL).to_sym
       configurations[env].push(blk)
     end
 
+    # @api private
     def each(environment, &blk)
       configurations.each do |env, blks|
         next unless matching_env?(environment, env)
@@ -20,8 +25,10 @@ module Hanami
 
     private
 
+    # @api private
     attr_reader :configurations
 
+    # @api private
     def matching_env?(environment, env)
       environment.to_sym == env ||
         env == ALL

data/lib/hanami/generators/app/application.rb.tt

@@ -13,7 +13,9 @@ module <%= config[:classified_app_name] %>
       #
       root __dir__
 
-      # Relative load paths where this application will recursively load the code.
+      # Relative load paths where this application will recursively load the
+      # code.
+      #
       # When you add new directories, remember to add them here.
       #
       load_paths << [
@@ -47,8 +49,10 @@ module <%= config[:classified_app_name] %>
       # host 'example.org'
 
       # URI port used by the routing system to generate absolute URLs
-      # Argument: An object coercible to integer, default to 80 if the scheme is http and 443 if it's https
-      # This SHOULD be configured only in case the application listens to that non standard ports
+      # Argument: An object coercible to integer, defaults to 80 if the scheme
+      # is http and 443 if it's https
+      #
+      # This should only be configured if app listens to non-standard ports
       #
       # port 443
 
@@ -56,13 +60,16 @@ module <%= config[:classified_app_name] %>
       # Argument: boolean to toggle the feature
       #           A Hash with options
       #
-      # Options: :domain   - The domain (String - nil by default, not required)
-      #          :path     - Restrict cookies to a relative URI (String - nil by default)
-      #          :max_age  - Cookies expiration expressed in seconds (Integer - nil by default)
-      #          :secure   - Restrict cookies to secure connections
-      #                      (Boolean - Automatically set on true if currently using a secure connection)
-      #                      See #scheme and #ssl?
-      #          :httponly - Prevent JavaScript access (Boolean - true by default)
+      # Options:
+      #   :domain   - The domain (String - nil by default, not required)
+      #   :path     - Restrict cookies to a relative URI
+      #               (String - nil by default)
+      #   :max_age  - Cookies expiration expressed in seconds
+      #               (Integer - nil by default)
+      #   :secure   - Restrict cookies to secure connections
+      #               (Boolean - Automatically true when using HTTPS)
+      #               See #scheme and #ssl?
+      #   :httponly - Prevent JavaScript access (Boolean - true by default)
       #
       # cookies true
       # or
@@ -81,24 +88,25 @@ module <%= config[:classified_app_name] %>
       # middleware.use Rack::Protection
 
       # Default format for the requests that don't specify an HTTP_ACCEPT header
-      # Argument: A symbol representation of a mime type, default to :html
+      # Argument: A symbol representation of a mime type, defaults to :html
       #
       # default_request_format :html
 
-      # Default format for responses that doesn't take into account the request format
-      # Argument: A symbol representation of a mime type, default to :html
+      # Default format for responses that don't consider the request format
+      # Argument: A symbol representation of a mime type, defaults to :html
       #
       # default_response_format :html
 
       # HTTP Body parsers
       # Parse non GET responses body for a specific mime type
-      # Argument: Symbol, which represent the format of the mime type (only `:json` is supported)
+      # Argument: Symbol, which represent the format of the mime type
+      #             (only `:json` is supported)
       #           Object, the parser
       #
       # body_parsers :json
 
       # When it's true and the router receives a non-encrypted request (http),
-      # it redirects to the secure equivalent resource (https). Default disabled.
+      # it redirects to the secure equivalent (https). Disabled by default.
       #
       # force_ssl true
 
@@ -180,8 +188,8 @@ module <%= config[:classified_app_name] %>
       #
       security.x_content_type_options 'nosniff'
 
-      # X-XSS-Protection is a HTTP header to determine the behavior of the browser
-      # in case an XSS attack is detected.
+      # X-XSS-Protection is a HTTP header to determine the behavior of the
+      # browser in case an XSS attack is detected.
       #
       # Read more at:
       #
@@ -190,16 +198,16 @@ module <%= config[:classified_app_name] %>
       #
       security.x_xss_protection '1; mode=block'
 
-      # Content-Security-Policy (CSP) is a HTTP header supported by modern browsers.
-      # It determines trusted sources of execution for dynamic contents
-      # (JavaScript) or other web related assets: stylesheets, images, fonts,
-      # plugins, etc.
+      # Content-Security-Policy (CSP) is a HTTP header supported by modern
+      # browsers. It determines trusted sources of execution for dynamic
+      # contents (JavaScript) or other web related assets: stylesheets, images,
+      # fonts, plugins, etc.
       #
       # Web applications can send this header to mitigate Cross Site Scripting
       # (XSS) attacks.
       #
-      # The default value allows images, scripts, AJAX, fonts and CSS from the same
-      # origin, and does not allow any other resources to load (eg object,
+      # The default value allows images, scripts, AJAX, fonts and CSS from the
+      # same origin, and does not allow any other resources to load (eg object,
       # frame, media, etc).
       #
       # Inline JavaScript is NOT allowed. To enable it, please use:

data/lib/hanami/generators/database_config.rb

@@ -1,9 +1,12 @@
 require 'shellwords'
 
 module Hanami
+  # @api private
   module Generators
+    # @api private
     class DatabaseConfig
 
+      # @api private
       SUPPORTED_ENGINES = {
         'mysql'      => { type: :sql,         mri: 'mysql2',  jruby: 'jdbc-mysql'    },
         'mysql2'     => { type: :sql,         mri: 'mysql2',  jruby: 'jdbc-mysql'    },
@@ -13,10 +16,15 @@ module Hanami
         'sqlite3'    => { type: :sql,         mri: 'sqlite3', jruby: 'jdbc-sqlite3'  }
       }.freeze
 
+      # @api private
       DEFAULT_ENGINE = 'sqlite'.freeze
 
-      attr_reader :engine, :name
+      # @api private
+      attr_reader :engine
+      # @api private
+      attr_reader :name
 
+      # @api private
       def initialize(engine, name)
         @engine = engine
         @name = name
@@ -27,6 +35,7 @@ module Hanami
         end
       end
 
+      # @api private
       def to_hash
         {
           gem: gem,
@@ -35,28 +44,34 @@ module Hanami
         }
       end
 
+      # @api private
       def type
         SUPPORTED_ENGINES[engine][:type]
       end
 
+      # @api private
       def sql?
         type == :sql
       end
 
+      # @api private
       def sqlite?
         ['sqlite', 'sqlite3'].include?(engine)
       end
 
       private
 
+      # @api private
       def platform
         Hanami::Utils.jruby? ? :jruby : :mri
       end
 
+      # @api private
       def platform_prefix
         'jdbc:'.freeze if Hanami::Utils.jruby?
       end
 
+      # @api private
       def uri
         {
           development: environment_uri(:development),
@@ -64,10 +79,12 @@ module Hanami
         }
       end
 
+      # @api private
       def gem
         SUPPORTED_ENGINES[engine][platform]
       end
 
+      # @api private
       def base_uri
         case engine
         when 'mysql', 'mysql2'
@@ -83,6 +100,7 @@ module Hanami
         end
       end
 
+      # @api private
       def environment_uri(environment)
         case engine
         when 'sqlite', 'sqlite3'