From 590997b481223d8c918e1040b81ec23582a34fba Mon Sep 17 00:00:00 2001
From: Marian13 <mariankostyk13895@gmail.com>
Date: Mon, 25 Sep 2023 01:25:42 +0300
Subject: [PATCH] chore(yard): parse docs inside included, intance_methods and
 class_methods blocks

---
 .yardopts                               |  3 ++
 Taskfile.yml                            |  8 ++++-
 yard/yard-convenient_service_concern.rb | 45 +++++++++++++++++++++++++
 3 files changed, 55 insertions(+), 1 deletion(-)
 create mode 100644 yard/yard-convenient_service_concern.rb

diff --git a/.yardopts b/.yardopts
index 3bc73e8584e..2d646a00b4d 100644
--- a/.yardopts
+++ b/.yardopts
@@ -1,4 +1,6 @@
 ##
+# NOTE: This config is used by `task docs:generate`.
+#
 # NOTE: `.yardopts` docs.
 # https://rubydoc.info/gems/yard/YARD/CLI/Yardoc
 #
@@ -9,5 +11,6 @@
 --markup-provider commonmarker
 --output-dir docs
 --tag internal --hide-tag internal
+--plugin convenient_service_concern
 'lib/**/*.rb' -
 README.md
diff --git a/Taskfile.yml b/Taskfile.yml
index 274a55d2bf9..b0fe2f3c1f2 100644
--- a/Taskfile.yml
+++ b/Taskfile.yml
@@ -339,7 +339,13 @@ tasks:
   #
   docs:generate:
     cmds:
-      - bundle exec yardoc
+      ##
+      # NOTE: yard supports plugins as gems only.
+      # - https://rubydoc.info/gems/yard/file/docs/GettingStarted.md#plugin-support
+      #
+      # NOTE: `RUBYLIB` is used to extend Ruby's `$LOAD_PATH`. This way yard treats `./yard` folder as a directory with custom gems.
+      #
+      - RUBYLIB=./yard bundle exec yardoc
 
   docs:generate:open:
     cmds:
diff --git a/yard/yard-convenient_service_concern.rb b/yard/yard-convenient_service_concern.rb
new file mode 100644
index 00000000000..607ba306596
--- /dev/null
+++ b/yard/yard-convenient_service_concern.rb
@@ -0,0 +1,45 @@
+require "yard"
+
+##
+# This file is used to allow parsing of yard docs inside `included`, `instance_methods` and `class_methods` blocks.
+#
+# It is loaded by the `RUBYLIB` ENV variable passed to `task docs:generate` in `Taskfile`.
+#
+# @see https://rubydoc.info/gems/yard/file/docs/GettingStarted.md#plugin-support
+# @see https://github.com/digitalcuisine/yard-activesupport-concern
+# @see https://github.com/digitalcuisine/yard-activesupport-concern/blob/v0.0.1/lib/yard-activesupport-concern.rb
+# @see https://stackoverflow.com/a/901109/12201472
+#
+module YARD
+  module Concern
+    class IncludedHandler < YARD::Handlers::Ruby::Base
+      handles method_call(:included)
+
+      namespace_only
+
+      def process
+        parse_block(statement.last.last, namespace: namespace, scope: :instance)
+      end
+    end
+
+    class InstanceMethodsHandler < YARD::Handlers::Ruby::Base
+      handles method_call(:instance_methods)
+
+      namespace_only
+
+      def process
+        parse_block(statement.last.last, namespace: namespace, scope: :instance)
+      end
+    end
+
+    class ClassMethodsHandler < YARD::Handlers::Ruby::Base
+      handles method_call(:class_methods)
+
+      namespace_only
+
+      def process
+        parse_block(statement.last.last, namespace: namespace, scope: :class)
+      end
+    end
+  end
+end