From eeb364253236757009b786091a84c3b353495fa2 Mon Sep 17 00:00:00 2001
From: Sean Collins <sean@cllns.com>
Date: Thu, 27 Jun 2024 11:49:01 -0600
Subject: [PATCH 1/4] Fix @api public/private to show Hanami::Action &
 subclasses

Fix @see references

Add @api public back to class
---
 lib/hanami/action.rb                 | 12 ++++++------
 lib/hanami/action/cache.rb           |  6 +++---
 lib/hanami/action/cookies.rb         |  2 +-
 lib/hanami/action/csrf_protection.rb |  1 -
 4 files changed, 10 insertions(+), 11 deletions(-)

diff --git a/lib/hanami/action.rb b/lib/hanami/action.rb
index 4e1015cb..5377283b 100644
--- a/lib/hanami/action.rb
+++ b/lib/hanami/action.rb
@@ -85,8 +85,8 @@ def self.gem_loader
     #
     #   @return [Config]
     #
-    #   @api public
-    #   @since 2.0.0
+    # @since 2.0.0
+    # @api public
 
     # @!scope instance
 
@@ -153,7 +153,7 @@ def self.params(_klass = nil)
     #
     #   @since 0.3.2
     #
-    #   @see Hanami::Action::Callbacks::ClassMethods#append_after
+    # @see #append_after
     #
     #   @example Method names (symbols)
     #     require "hanami/controller"
@@ -221,7 +221,7 @@ class << self
     #
     #   @since 0.3.2
     #
-    #   @see Hanami::Action::Callbacks::ClassMethods#append_before
+    # @see #append_before
     def self.append_after(...)
       config.after_callbacks.append(...)
     end
@@ -246,7 +246,7 @@ class << self
     #
     #   @since 0.3.2
     #
-    #   @see Hanami::Action::Callbacks::ClassMethods#prepend_after
+    # @see #prepend_after
     def self.prepend_before(...)
       config.before_callbacks.prepend(...)
     end
@@ -266,7 +266,7 @@ def self.prepend_before(...)
     #
     #   @since 0.3.2
     #
-    #   @see Hanami::Action::Callbacks::ClassMethods#prepend_before
+    # @see #prepend_before
     def self.prepend_after(...)
       config.after_callbacks.prepend(...)
     end
diff --git a/lib/hanami/action/cache.rb b/lib/hanami/action/cache.rb
index 5873610c..e33b12dd 100644
--- a/lib/hanami/action/cache.rb
+++ b/lib/hanami/action/cache.rb
@@ -6,9 +6,9 @@ class Action
     #
     # @since 0.3.0
     #
-    # @see Hanami::Action::Cache::ClassMethods#cache_control
-    # @see Hanami::Action::Cache::ClassMethods#expires
-    # @see Hanami::Action::Cache::ClassMethods#fresh
+    # @see Hanami::Action::Response#cache_control
+    # @see Hanami::Action::Response#expires
+    # @see Hanami::Action::Response#fresh
     module Cache
       # Override Ruby's hook for modules.
       # It includes exposures logic
diff --git a/lib/hanami/action/cookies.rb b/lib/hanami/action/cookies.rb
index 4b011f91..33fce652 100644
--- a/lib/hanami/action/cookies.rb
+++ b/lib/hanami/action/cookies.rb
@@ -8,7 +8,7 @@ class Action
     #
     # @since 0.1.0
     #
-    # @see Hanami::Action::Cookies#cookies
+    # @see Hanami::Action::Response#cookies
     module Cookies
       private
 
diff --git a/lib/hanami/action/csrf_protection.rb b/lib/hanami/action/csrf_protection.rb
index c6d1d014..ea39d773 100644
--- a/lib/hanami/action/csrf_protection.rb
+++ b/lib/hanami/action/csrf_protection.rb
@@ -6,7 +6,6 @@
 require_relative "errors"
 
 module Hanami
-  # @api private
   class Action
     # CSRF Protection
     #

From 2c73ece2549921cbaf239e5d60da576ab1a767eb Mon Sep 17 00:00:00 2001
From: Sean Collins <sean@cllns.com>
Date: Thu, 27 Jun 2024 18:40:05 -0600
Subject: [PATCH 2/4] Fix more docs

---
 lib/hanami/action.rb          | 17 ++++++++++-------
 lib/hanami/action/response.rb |  2 +-
 2 files changed, 11 insertions(+), 8 deletions(-)

diff --git a/lib/hanami/action.rb b/lib/hanami/action.rb
index 5377283b..46fa110c 100644
--- a/lib/hanami/action.rb
+++ b/lib/hanami/action.rb
@@ -83,7 +83,7 @@ def self.gem_loader
     #       config.format :json
     #     end
     #
-    #   @return [Config]
+    # @return [Config]
     #
     # @since 2.0.0
     # @api public
@@ -138,7 +138,7 @@ def self.params(_klass = nil)
             "To use `params`, please add 'hanami/validations' gem to your Gemfile"
     end
 
-    # @overload self.append_before(*callbacks, &block)
+    # @overload append_before(*callbacks, &block)
     #   Define a callback for an Action.
     #   The callback will be executed **before** the action is called, in the
     #   order they are added.
@@ -153,7 +153,7 @@ def self.params(_klass = nil)
     #
     #   @since 0.3.2
     #
-    # @see #append_after
+    #   @see #append_after
     #
     #   @example Method names (symbols)
     #     require "hanami/controller"
@@ -206,7 +206,7 @@ class << self
       alias_method :before, :append_before
     end
 
-    # @overload self.append_after(*callbacks, &block)
+    # @overload append_after(*callbacks, &block)
     #   Define a callback for an Action.
     #   The callback will be executed **after** the action is called, in the
     #   order they are added.
@@ -231,7 +231,7 @@ class << self
       alias_method :after, :append_after
     end
 
-    # @overload self.prepend_before(*callbacks, &block)
+    # @overload prepend_before(*callbacks, &block)
     #   Define a callback for an Action.
     #   The callback will be executed **before** the action is called.
     #   It will add the callback at the beginning of the callbacks' chain.
@@ -251,7 +251,7 @@ def self.prepend_before(...)
       config.before_callbacks.prepend(...)
     end
 
-    # @overload self.prepend_after(*callbacks, &block)
+    # @overload prepend_after(*callbacks, &block)
     #   Define a callback for an Action.
     #   The callback will be executed **after** the action is called.
     #   It will add the callback at the beginning of the callbacks' chain.
@@ -334,11 +334,14 @@ def call(env)
 
     protected
 
-    # Hook for subclasses to apply behavior as part of action invocation
+    # Hook for subclasses to apply behavior as part of action invocation.
+    #
+    # This is the method you'll implement in your actions.
     #
     # @param request [Hanami::Action::Request]
     # @param response [Hanami::Action::Response]
     #
+    # @abstract
     # @since 2.0.0
     # @api public
     def handle(request, response)
diff --git a/lib/hanami/action/response.rb b/lib/hanami/action/response.rb
index a8cb994b..5185d6f7 100644
--- a/lib/hanami/action/response.rb
+++ b/lib/hanami/action/response.rb
@@ -14,7 +14,7 @@ class Action
     # @see http://www.rubydoc.info/gems/rack/Rack/Response
     #
     # @since 2.0.0
-    # @api private
+    # @api public
     class Response < ::Rack::Response
       # @since 2.0.0
       # @api private

From 2392a5fbc3c5aeaa3e48b4384c34ea013f923b3d Mon Sep 17 00:00:00 2001
From: Sean Collins <sean@cllns.com>
Date: Thu, 27 Jun 2024 18:40:45 -0600
Subject: [PATCH 3/4] Add class name to @see

---
 lib/hanami/action.rb | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/lib/hanami/action.rb b/lib/hanami/action.rb
index 46fa110c..65794686 100644
--- a/lib/hanami/action.rb
+++ b/lib/hanami/action.rb
@@ -153,7 +153,7 @@ def self.params(_klass = nil)
     #
     #   @since 0.3.2
     #
-    #   @see #append_after
+    #   @see Action#append_after
     #
     #   @example Method names (symbols)
     #     require "hanami/controller"
@@ -221,7 +221,7 @@ class << self
     #
     #   @since 0.3.2
     #
-    # @see #append_before
+    # @see Action#append_before
     def self.append_after(...)
       config.after_callbacks.append(...)
     end
@@ -246,7 +246,7 @@ class << self
     #
     #   @since 0.3.2
     #
-    # @see #prepend_after
+    # @see Action#prepend_after
     def self.prepend_before(...)
       config.before_callbacks.prepend(...)
     end
@@ -266,7 +266,7 @@ def self.prepend_before(...)
     #
     #   @since 0.3.2
     #
-    # @see #prepend_before
+    # @see Action#prepend_before
     def self.prepend_after(...)
       config.after_callbacks.prepend(...)
     end

From 3c52500239a2e1f7a8ce57b1a3d9e1f22df13304 Mon Sep 17 00:00:00 2001
From: Sean Collins <sean@cllns.com>
Date: Thu, 27 Jun 2024 19:04:23 -0600
Subject: [PATCH 4/4] Fix more API docs

---
 lib/hanami/action.rb                 | 6 ++----
 lib/hanami/action/cache.rb           | 1 +
 lib/hanami/action/config.rb          | 4 +---
 lib/hanami/action/cookie_jar.rb      | 2 +-
 lib/hanami/action/cookies.rb         | 3 ++-
 lib/hanami/action/csrf_protection.rb | 4 ++--
 6 files changed, 9 insertions(+), 11 deletions(-)

diff --git a/lib/hanami/action.rb b/lib/hanami/action.rb
index 65794686..ba07fb31 100644
--- a/lib/hanami/action.rb
+++ b/lib/hanami/action.rb
@@ -364,8 +364,8 @@ def handle(request, response)
     #
     # @since 0.2.0
     #
-    # @see Hanami::Action::Throwable#handle_exception
-    # @see Hanami::Http::Status:ALL
+    # @see Hanami::Action.handle_exception
+    # @see https://rubydoc.info/github/rack/rack/Rack/Utils
     #
     # @example Basic usage
     #   require "hanami/controller"
@@ -528,8 +528,6 @@ def _run_after_callbacks(*args)
     #
     # @since 0.5.0
     #
-    # @see Hanami::Action#_requires_no_body?
-    #
     # @example
     #   require "hanami/controller"
     #
diff --git a/lib/hanami/action/cache.rb b/lib/hanami/action/cache.rb
index e33b12dd..7bfc2aba 100644
--- a/lib/hanami/action/cache.rb
+++ b/lib/hanami/action/cache.rb
@@ -5,6 +5,7 @@ class Action
     # Cache type API
     #
     # @since 0.3.0
+    # @api private
     #
     # @see Hanami::Action::Response#cache_control
     # @see Hanami::Action::Response#expires
diff --git a/lib/hanami/action/config.rb b/lib/hanami/action/config.rb
index 8481ab00..0327d12f 100644
--- a/lib/hanami/action/config.rb
+++ b/lib/hanami/action/config.rb
@@ -137,15 +137,13 @@ def format(*formats)
 
       # @!attribute [rw] root_directory
       #
-      #   Sets the the for the public directory, which is used for file downloads.
+      #   Sets the the root directory for the public directory, which is used for file downloads.
       #   This must be an existent directory.
       #
       #   Defaults to the current working directory.
       #
       #   @return [String] the directory path
       #
-      #   @api private
-      #
       #   @since 1.0.0
 
       # @!attribute [rw] public_directory
diff --git a/lib/hanami/action/cookie_jar.rb b/lib/hanami/action/cookie_jar.rb
index fd38b54a..258729e6 100644
--- a/lib/hanami/action/cookie_jar.rb
+++ b/lib/hanami/action/cookie_jar.rb
@@ -11,7 +11,7 @@ class Action
     #
     # @since 0.1.0
     #
-    # @see Hanami::Action::Cookies#cookies
+    # @see Hanami::Action::Response#cookies
     class CookieJar
       # @since 0.4.5
       # @api private
diff --git a/lib/hanami/action/cookies.rb b/lib/hanami/action/cookies.rb
index 33fce652..491f95f1 100644
--- a/lib/hanami/action/cookies.rb
+++ b/lib/hanami/action/cookies.rb
@@ -4,7 +4,8 @@ module Hanami
   class Action
     # Cookies API
     #
-    # This module isn't included by default.
+    # If you want cookies in your actions then include this module.
+    # It's not included by default.
     #
     # @since 0.1.0
     #
diff --git a/lib/hanami/action/csrf_protection.rb b/lib/hanami/action/csrf_protection.rb
index ea39d773..4965d157 100644
--- a/lib/hanami/action/csrf_protection.rb
+++ b/lib/hanami/action/csrf_protection.rb
@@ -29,8 +29,8 @@ class Action
     #
     # @since 0.4.0
     #
-    # @see https://www.owasp.org/index.php/Cross-Site_Request_Forgery_%28CSRF%29
-    # @see https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)_Prevention_Cheat_Sheet
+    # @see https://owasp.org/www-community/attacks/csrf
+    # @see https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html
     #
     # @example Custom Handling
     #   module Web::Controllers::Books