From 7c4b4dcdcb274abcd3bb8dce9d2ec4946cb8754f Mon Sep 17 00:00:00 2001 From: Luca Guidi Date: Mon, 13 Mar 2017 11:07:42 +0100 Subject: [PATCH] API docs. Made flash public API. [ci skip] --- lib/hanami/action/base_params.rb | 3 +++ lib/hanami/action/cache.rb | 7 +---- lib/hanami/action/cache/cache_control.rb | 16 +++++++++--- lib/hanami/action/cache/conditional_get.rb | 23 ++++++++++++++++- lib/hanami/action/cache/directives.rb | 27 ++++++++++++++++++- lib/hanami/action/cache/expires.rb | 18 ++++++++++--- lib/hanami/action/callbacks.rb | 4 +++ lib/hanami/action/configurable.rb | 1 + lib/hanami/action/cookies.rb | 1 - lib/hanami/action/exposable/guard.rb | 2 ++ lib/hanami/action/head.rb | 1 - lib/hanami/action/mime.rb | 2 +- lib/hanami/action/params.rb | 30 ++++++++++++++++++++++ lib/hanami/action/rack.rb | 3 +++ lib/hanami/action/rack/callable.rb | 2 +- lib/hanami/action/request.rb | 1 - lib/hanami/action/session.rb | 1 - lib/hanami/action/throwable.rb | 2 ++ lib/hanami/action/validatable.rb | 15 ++++++----- lib/hanami/controller.rb | 8 ++++-- 20 files changed, 137 insertions(+), 30 deletions(-) diff --git a/lib/hanami/action/base_params.rb b/lib/hanami/action/base_params.rb index 80615ed0..bec235db 100644 --- a/lib/hanami/action/base_params.rb +++ b/lib/hanami/action/base_params.rb @@ -7,12 +7,14 @@ class BaseParams # The key that returns raw input from the Rack env # # @since 0.7.0 + # @api private RACK_INPUT = 'rack.input'.freeze # The key that returns router params from the Rack env # This is a builtin integration for Hanami::Router # # @since 0.7.0 + # @api private ROUTER_PARAMS = 'router.params'.freeze # The key that returns Rack session params from the Rack env @@ -46,6 +48,7 @@ class BaseParams # @return [Params] # # @since 0.7.0 + # @api private def initialize(env) @env = env @raw = _extract_params diff --git a/lib/hanami/action/cache.rb b/lib/hanami/action/cache.rb index 28ee2fb2..4679c7b6 100644 --- a/lib/hanami/action/cache.rb +++ b/lib/hanami/action/cache.rb @@ -20,7 +20,7 @@ module Cache # @since 0.3.0 # @api private # - # @see http://www.ruby-doc.org/core-2.1.2/Module.html#method-i-included + # @see http://www.ruby-doc.org/core/Module.html#method-i-included def self.included(base) base.class_eval do include CacheControl, Expires @@ -51,7 +51,6 @@ def self.included(base) # @return void # # @since 0.3.0 - # @api public # # @example # require 'hanami/controller' @@ -74,7 +73,6 @@ def self.included(base) # # end # end - # def cache_control(*values) cache_control = CacheControl::Directives.new(*values) headers.merge!(cache_control.headers) @@ -91,7 +89,6 @@ def cache_control(*values) # @return void # # @since 0.3.0 - # @api public # # @example # require 'hanami/controller' @@ -115,7 +112,6 @@ def cache_control(*values) # # end # end - # def expires(amount, *values) expires = Expires::Directives.new(amount, *values) headers.merge!(expires.headers) @@ -132,7 +128,6 @@ def expires(amount, *values) # @return void # # @since 0.3.0 - # @api public # # @example # require 'hanami/controller' diff --git a/lib/hanami/action/cache/cache_control.rb b/lib/hanami/action/cache/cache_control.rb index 29cef3e2..0b39ff7a 100644 --- a/lib/hanami/action/cache/cache_control.rb +++ b/lib/hanami/action/cache/cache_control.rb @@ -3,19 +3,19 @@ module Hanami module Action module Cache - # Module with Cache-Control logic # # @since 0.3.0 # @api private module CacheControl - # The HTTP header for Cache-Control # # @since 0.3.0 # @api private HEADER = 'Cache-Control'.freeze + # @since 0.3.0 + # @api private def self.included(base) base.class_eval do extend ClassMethods @@ -23,11 +23,17 @@ def self.included(base) end end + # @since 0.3.0 + # @api private module ClassMethods + # @since 0.3.0 + # @api private def cache_control(*values) @cache_control_directives ||= Directives.new(*values) end + # @since 0.3.0 + # @api private def cache_control_directives @cache_control_directives || Object.new.tap do |null_object| def null_object.headers @@ -51,14 +57,16 @@ def finish # Class which stores CacheControl values # # @since 0.3.0 - # # @api private - # class Directives + # @since 0.3.0 + # @api private def initialize(*values) @directives = Hanami::Action::Cache::Directives.new(*values) end + # @since 0.3.0 + # @api private def headers if @directives.any? { HEADER => @directives.join(', ') } diff --git a/lib/hanami/action/cache/conditional_get.rb b/lib/hanami/action/cache/conditional_get.rb index d4b5d6a1..d7697efd 100644 --- a/lib/hanami/action/cache/conditional_get.rb +++ b/lib/hanami/action/cache/conditional_get.rb @@ -25,22 +25,29 @@ module Cache # # @since 0.3.0 # @api private - # class ETag + # @since 0.3.0 + # @api private def initialize(env, value) @env, @value = env, value end + # @since 0.3.0 + # @api private def fresh? none_match && @value == none_match end + # @since 0.3.0 + # @api private def header { ETAG => @value } if none_match end private + # @since 0.3.0 + # @api private def none_match @env[IF_NONE_MATCH] end @@ -51,20 +58,28 @@ def none_match # @since 0.3.0 # @api private class LastModified + # @since 0.3.0 + # @api private def initialize(env, value) @env, @value = env, value end + # @since 0.3.0 + # @api private def fresh? !Hanami::Utils::Blank.blank?(modified_since) && Time.httpdate(modified_since).to_i >= @value.to_i end + # @since 0.3.0 + # @api private def header { LAST_MODIFIED => @value.httpdate } if modified_since end private + # @since 0.3.0 + # @api private def modified_since @env[IF_MODIFIED_SINCE] end @@ -76,14 +91,20 @@ def modified_since # @since 0.3.0 # @api private class ConditionalGet + # @since 0.3.0 + # @api private def initialize(env, options) @validations = [ ETag.new(env, options[:etag]), LastModified.new(env, options[:last_modified]) ] end + # @since 0.3.0 + # @api private def fresh? yield if @validations.any?(&:fresh?) end + # @since 0.3.0 + # @api private def headers @validations.map(&:header).compact.reduce Hash.new, :merge end diff --git a/lib/hanami/action/cache/directives.rb b/lib/hanami/action/cache/directives.rb index 76ce5101..e9e6cd88 100644 --- a/lib/hanami/action/cache/directives.rb +++ b/lib/hanami/action/cache/directives.rb @@ -1,7 +1,6 @@ module Hanami module Action module Cache - # Cache-Control directives which have values # # @since 0.3.0 @@ -21,16 +20,24 @@ module Cache # @since 0.3.0 # @api private class ValueDirective + # @since 0.3.0 + # @api private attr_reader :name + # @since 0.3.0 + # @api private def initialize(name, value) @name, @value = name, value end + # @since 0.3.0 + # @api private def to_str "#{@name.to_s.tr('_', '-')}=#{@value.to_i}" end + # @since 0.3.0 + # @api private def valid? VALUE_DIRECTIVES.include? @name end @@ -43,16 +50,24 @@ def valid? # @since 0.3.0 # @api private class NonValueDirective + # @since 0.3.0 + # @api private attr_reader :name + # @since 0.3.0 + # @api private def initialize(name) @name = name end + # @since 0.3.0 + # @api private def to_str @name.to_s.tr('_', '-') end + # @since 0.3.0 + # @api private def valid? NON_VALUE_DIRECTIVES.include? @name end @@ -65,6 +80,8 @@ def valid? class Directives include Enumerable + # @since 0.3.0 + # @api private def initialize(*values) @directives = [] values.each do |directive_key| @@ -76,20 +93,28 @@ def initialize(*values) end end + # @since 0.3.0 + # @api private def each @directives.each { |d| yield d } end + # @since 0.3.0 + # @api private def <<(directive) @directives << directive if directive.valid? end + # @since 0.3.0 + # @api private def values @directives.delete_if do |directive| directive.name == :public && @directives.map(&:name).include?(:private) end end + # @since 0.3.0 + # @api private def join(separator) values.join(separator) end diff --git a/lib/hanami/action/cache/expires.rb b/lib/hanami/action/cache/expires.rb index 3ad2bbeb..22ccc69f 100644 --- a/lib/hanami/action/cache/expires.rb +++ b/lib/hanami/action/cache/expires.rb @@ -3,19 +3,19 @@ module Hanami module Action module Cache - # Module with Expires logic # # @since 0.3.0 # @api private module Expires - # The HTTP header for Expires # # @since 0.3.0 # @api private HEADER = 'Expires'.freeze + # @since 0.3.0 + # @api private def self.included(base) base.class_eval do extend ClassMethods @@ -23,11 +23,17 @@ def self.included(base) end end + # @since 0.3.0 + # @api private module ClassMethods + # @since 0.3.0 + # @api private def expires(amount, *values) @expires_directives ||= Directives.new(amount, *values) end + # @since 0.3.0 + # @api private def expires_directives @expires_directives || Object.new.tap do |null_object| def null_object.headers @@ -51,21 +57,25 @@ def finish # Class which stores Expires directives # # @since 0.3.0 - # # @api private - # class Directives + # @since 0.3.0 + # @api private def initialize(amount, *values) @amount = amount @cache_control = Hanami::Action::Cache::CacheControl::Directives.new(*(values << { max_age: amount })) end + # @since 0.3.0 + # @api private def headers { HEADER => time.httpdate }.merge(@cache_control.headers) end private + # @since 0.3.0 + # @api private def time Time.now + @amount.to_i end diff --git a/lib/hanami/action/callbacks.rb b/lib/hanami/action/callbacks.rb index 607b1bb0..81933363 100644 --- a/lib/hanami/action/callbacks.rb +++ b/lib/hanami/action/callbacks.rb @@ -197,10 +197,14 @@ def call(params) end private + # @since 0.1.0 + # @api private def _run_before_callbacks(params) self.class.before_callbacks.run(self, params) end + # @since 0.1.0 + # @api private def _run_after_callbacks(params) self.class.after_callbacks.run(self, params) end diff --git a/lib/hanami/action/configurable.rb b/lib/hanami/action/configurable.rb index b1198744..ffdffb59 100644 --- a/lib/hanami/action/configurable.rb +++ b/lib/hanami/action/configurable.rb @@ -41,6 +41,7 @@ def self.included(base) private + # @since 0.2.0 def configuration self.class.configuration end diff --git a/lib/hanami/action/cookies.rb b/lib/hanami/action/cookies.rb index 0bc6b872..7ffb1c6b 100644 --- a/lib/hanami/action/cookies.rb +++ b/lib/hanami/action/cookies.rb @@ -23,7 +23,6 @@ module Cookies # @return [Hanami::Action::CookieJar] cookies # # @since 0.1.0 - # @api public # # @see Hanami::Controller::Configuration#cookies # @see Hanami::Action::CookieJar#[]= diff --git a/lib/hanami/action/exposable/guard.rb b/lib/hanami/action/exposable/guard.rb index 74baa3ab..50293af5 100644 --- a/lib/hanami/action/exposable/guard.rb +++ b/lib/hanami/action/exposable/guard.rb @@ -15,6 +15,7 @@ module Exposable # Prevents exposure of reserved words # # @since 0.7.1 + # @api private # # @see Hanami::Action::Exposable::Guard::ClassMethods#expose # @see Hanami::Action::Exposable::Guard::ClassMethods#reserved_word? @@ -47,6 +48,7 @@ module ClassMethods # @return [void] # # @since 0.7.1 + # @api private def expose(*names) detect_reserved_words!(names) diff --git a/lib/hanami/action/head.rb b/lib/hanami/action/head.rb index 02d0464c..1ef5fa25 100644 --- a/lib/hanami/action/head.rb +++ b/lib/hanami/action/head.rb @@ -78,7 +78,6 @@ def _requires_no_body? # quota via X-Rate-Limit. # # @since 0.5.0 - # @api public # # @see Hanami::Action::HEAD#finish # diff --git a/lib/hanami/action/mime.rb b/lib/hanami/action/mime.rb index 1c074867..b332dbca 100644 --- a/lib/hanami/action/mime.rb +++ b/lib/hanami/action/mime.rb @@ -40,7 +40,7 @@ module Mime # @api private DEFAULT_CHARSET = 'utf-8'.freeze - # Most commom mime types used for responses + # Most commom MIME Types used for responses # # @since 1.0.0.beta1 # @api private diff --git a/lib/hanami/action/params.rb b/lib/hanami/action/params.rb index cdab6351..1d33b8d7 100644 --- a/lib/hanami/action/params.rb +++ b/lib/hanami/action/params.rb @@ -26,6 +26,34 @@ def self._base_rules end end + # Define params validations + # + # @param blk [Proc] the validations definitions + # + # @since 0.7.0 + # + # @see http://hanamirb.org/guides/validations/overview/ + # + # @example + # class Signup + # MEGABYTE = 1024 ** 2 + # include Hanami::Action + # + # params do + # required(:first_name).filled(:str?) + # required(:last_name).filled(:str?) + # required(:email).filled?(:str?, format?: /\A.+@.+\z/) + # required(:password).filled(:str?).confirmation + # required(:terms_of_service).filled(:bool?) + # required(:age).filled(:int?, included_in?: 18..99) + # optional(:avatar).filled(size?: 1..(MEGABYTE * 3)) + # end + # + # def call(params) + # halt 400 unless params.valid? + # # ... + # end + # end def self.params(&blk) validations(&blk || ->() {}) end @@ -37,6 +65,7 @@ def self.params(&blk) # @return [Params] # # @since 0.1.0 + # @api private def initialize(env) @env = env super(_extract_params) @@ -115,6 +144,7 @@ def to_h private + # @api private def _params @result.output.merge(_router_params) end diff --git a/lib/hanami/action/rack.rb b/lib/hanami/action/rack.rb index 53a1f2ae..d4c22f48 100644 --- a/lib/hanami/action/rack.rb +++ b/lib/hanami/action/rack.rb @@ -98,10 +98,12 @@ def self.included(base) end end + # @api private module ClassMethods # Build rack builder # # @return [Rack::Builder] + # @api private def rack_builder @rack_builder ||= begin extend Hanami::Action::Rack::Callable @@ -242,6 +244,7 @@ def request @request ||= ::Hanami::Action::Request.new(@_env) end + # Return parsed request body def parsed_request_body @_env.fetch(ROUTER_PARSED_BODY, nil) end diff --git a/lib/hanami/action/rack/callable.rb b/lib/hanami/action/rack/callable.rb index 6b0ab72e..f3d8b54a 100644 --- a/lib/hanami/action/rack/callable.rb +++ b/lib/hanami/action/rack/callable.rb @@ -1,4 +1,3 @@ - module Hanami module Action module Rack @@ -10,6 +9,7 @@ module Callable # see the examples below. # # @since 0.4.0 + # @api private # # @see Hanami::Action::Rack::ClassMethods#rack_builder # @see Hanami::Action::Rack::ClassMethods#use diff --git a/lib/hanami/action/request.rb b/lib/hanami/action/request.rb index e3ac1c7d..860dda37 100644 --- a/lib/hanami/action/request.rb +++ b/lib/hanami/action/request.rb @@ -9,7 +9,6 @@ module Action # # @see http://www.rubydoc.info/gems/rack/Rack/Request class Request < ::Rack::Request - # @raise [NotImplementedError] # # @since 0.3.1 diff --git a/lib/hanami/action/session.rb b/lib/hanami/action/session.rb index d05127db..3a3926d5 100644 --- a/lib/hanami/action/session.rb +++ b/lib/hanami/action/session.rb @@ -80,7 +80,6 @@ def errors # @return [Hanami::Action::Flash] a Flash instance # # @since 0.3.0 - # @api private # # @see Hanami::Action::Flash def flash diff --git a/lib/hanami/action/throwable.rb b/lib/hanami/action/throwable.rb index 1bc4a290..35f49927 100644 --- a/lib/hanami/action/throwable.rb +++ b/lib/hanami/action/throwable.rb @@ -28,6 +28,8 @@ module Throwable # @see https://github.com/hanami/controller/issues/133 RACK_EXCEPTION = 'rack.exception'.freeze + # @since 0.1.0 + # @api private def self.included(base) base.extend ClassMethods end diff --git a/lib/hanami/action/validatable.rb b/lib/hanami/action/validatable.rb index be49bee3..ccbf97ff 100644 --- a/lib/hanami/action/validatable.rb +++ b/lib/hanami/action/validatable.rb @@ -9,6 +9,8 @@ module Validatable # @since 0.3.0 PARAMS_CLASS_NAME = 'Params'.freeze + # @api private + # @since 0.1.0 def self.included(base) base.extend ClassMethods end @@ -48,6 +50,7 @@ module ClassMethods # @since 0.3.0 # # @see Hanami::Action::Params + # @see http://hanamirb.org/guides/validations/overview/ # # @example Anonymous Block # require 'hanami/controller' @@ -56,9 +59,9 @@ module ClassMethods # include Hanami::Action # # params do - # param :first_name - # param :last_name - # param :email + # required(:first_name) + # required(:last_name) + # required(:email) # end # # def call(params) @@ -74,9 +77,9 @@ module ClassMethods # require 'hanami/controller' # # class SignupParams < Hanami::Action::Params - # param :first_name - # param :last_name - # param :email + # required(:first_name) + # required(:last_name) + # required(:email) # end # # class Signup diff --git a/lib/hanami/controller.rb b/lib/hanami/controller.rb index 2b8b78a8..9236f355 100644 --- a/lib/hanami/controller.rb +++ b/lib/hanami/controller.rb @@ -4,6 +4,9 @@ require 'hanami/controller/version' require 'hanami/controller/error' +# Hanami +# +# @since 0.1.0 module Hanami # A set of logically grouped actions # @@ -37,6 +40,8 @@ module Controller # # @see Hanami::Action::Mime#format= class UnknownFormatError < Hanami::Controller::Error + # @since 0.2.0 + # @api private def initialize(format) super("Cannot find a corresponding Mime type for '#{ format }'. Please configure it with Hanami::Controller::Configuration#format.") end @@ -130,7 +135,7 @@ def self.dupe # # @return [Module] a copy of Hanami::Controller # - # @since 0.2.0 + # @since 0.2.0 # # @see Hanami::Controller#dupe # @see Hanami::Controller::Configuration @@ -252,4 +257,3 @@ def self.load! end end end -