rails-annotate-solargraph 0.2.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f1d0f284eac106e51e1abc19eec0d7b8790aab9ee188e1cabea5defb04417da
-  data.tar.gz: 392519ce6da6313e8a3308dee6f54b66629ee108120b8abcb94e1d838dc86470
+  metadata.gz: 4ca6f0073923760a583abb52af713540b2f53cf6e8dd896584e3a76b97444c8b
+  data.tar.gz: a07141ca737ee0c60153cabd5e28540d3507ba09401b4cc31d30ea491bc32eb2
 SHA512:
-  metadata.gz: 23e25ae122d969be4f5d4081638592e3db7d6ab46adf60cdaf82057953441576d842bc2db79af664371637e332b25c5fee091fe930e53ffd88f97d78a04533c9
-  data.tar.gz: 43d0752100b231426877a84665ba8030d5121b8f0d7b07549f2312c7e30cb7f1c0f9c9807b99bc085394fd369cb81a95ec63c15366e92a9eb96116fdb91b8fee
+  metadata.gz: f3a40df235de87414059053670f344e0e6606b9538ecba40b7fbb2c849c07f8009e5cec055e485033bae5529bce9146d2369d76b8a6ab4288664703bef29da2f
+  data.tar.gz: d920e8b59c64f57d22fba128b4db1acffd88b718799e24e2f361d43e99ae6505258faa2665f57fafdee9d9cd6d4dc47231c9e5e7bb99a7e687707c2642e211e5

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+## [0.3.0] - 2022-04-17
+
+- `has_many :through` and `has_one :through` relations get documented
+
 ## [0.2.3] - 2022-04-16
 
 - A nicer fix for the previous problem
@@ -15,6 +19,7 @@
 ## [0.2.0] - 2022-04-16
 
 - Associations get fully documented
+- `has_many`, `has_one` and `belongs_to` relations get documented
 
 ## [0.1.1] - 2022-04-15
 
@@ -24,4 +29,5 @@
 
 - Initial release
 - Automatic generation of annotations after migrations
+- Database fields get documented
 - Manual rake tasks `annotate:solargraph:generate`, `annotate:solargraph:remove`

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rails-annotate-solargraph (0.2.3)
+    rails-annotate-solargraph (0.3.0)
       rails (>= 5.0, < 8.0)
 
 GEM

data/lib/rails/annotate/solargraph/model.rb

@@ -142,37 +142,57 @@ module Rails
           @klass.table_name[..-2]
         end
 
+        # @param reflection [ActiveRecord::Reflection::AbstractReflection]
+        # @return [Class]
+        def reflection_class(reflection)
+          reflection.klass
+        rescue ::NameError
+          Object
+        end
+
+        # @param reflection [ActiveRecord::Reflection::AbstractReflection]
+        # @return [String]
+        def reflection_foreign_key(reflection)
+          reflection.try(:foreign_key) || '<unknown>'
+        end
+
+        # @param klass [Class]
+        # @return [String]
+        def class_table_name(klass)
+          klass.try(:table_name) || '<unknown>'
+        end
+
         # @param doc_string [String]
         # @param attr_name [String]
         # @param reflection [ActiveRecord::Reflection::AbstractReflection]
         # @return [void]
         def document_relation(doc_string, attr_name, reflection)
-          reflection_class = begin
-            reflection.klass
-          rescue ::NameError
-            Object
-          end
-
-          associated_table_name = reflection_class.try(:table_name) || '<unknown>'
-          foreign_key = reflection.try(:foreign_key) || '<unknown>'
-          db_description = \
+          reflection_klass = reflection_class(reflection)
+          type_docstring, db_description = \
             case reflection
             when ::ActiveRecord::Reflection::BelongsToReflection
-              type_docstring = reflection_class
-              "`belongs_to` relation with `#{reflection_class}`. Database column `#{@klass.table_name}.#{foreign_key}`."
+              belongs_to_description(reflection_klass,
+                                     class_table_name(@klass),
+                                     reflection_foreign_key(reflection))
             when ::ActiveRecord::Reflection::HasOneReflection
-              type_docstring = reflection_class
-              "`has_one` relation with `#{reflection_class}`. Database column `#{associated_table_name}.#{foreign_key}`."
+              has_one_description(reflection_klass,
+                                  class_table_name(reflection_klass),
+                                  reflection_foreign_key(reflection))
             when ::ActiveRecord::Reflection::HasManyReflection
-              type_docstring = "Array<#{reflection_class}>"
-              "`has_many` relation with `#{reflection_class}`. Database column `#{associated_table_name}.#{foreign_key}`."
+              has_many_description(reflection_klass,
+                                   class_table_name(reflection_klass),
+                                   reflection_foreign_key(reflection))
+            when ::ActiveRecord::Reflection::ThroughReflection
+              through_description(reflection)
+            else
+              [::Object.to_s, '']
             end
 
           doc_string << <<~DOC
-            #     # #{db_description}
+            #     ##{db_description}
             #     # @param val [#{type_docstring}, nil]
             #     def #{attr_name}=(val); end
-            #     # #{db_description}
+            #     ##{db_description}
             #     # @return [#{type_docstring}, nil]
             #     def #{attr_name}; end
           DOC
@@ -187,7 +207,7 @@ module Rails
             model_class.reflections[klass_relation_name]&.options&.[](:as)&.to_sym == attr_name.to_sym
           end
 
-          classes_string = classes.join(', ')
+          classes_string = classes.empty? ? ::Object.to_s : classes.join(', ')
           doc_string << <<~DOC
             #     # Polymorphic relation. Database columns `#{@klass.table_name}.#{attr_name}_id` and `#{@klass.table_name}.#{attr_name}_type`.
             #     # @param val [#{classes_string}, nil]
@@ -198,6 +218,91 @@ module Rails
           DOC
         end
 
+        # @param reflection [ActiveRecord::Reflection::AbstractReflection]
+        # @return [Array<String>]
+        def through_description(reflection)
+          through_klass = reflection_class(reflection.through_reflection)
+
+          case (reflection.__send__(:delegate_reflection) rescue nil)
+          when ::ActiveRecord::Reflection::HasOneReflection
+            has_one_description(reflection_class(reflection.source_reflection),
+                                class_table_name(through_klass),
+                                reflection_foreign_key(reflection.source_reflection),
+                                through: through_klass)
+          when ::ActiveRecord::Reflection::HasManyReflection
+            has_many_description(reflection_class(reflection.source_reflection),
+                                 class_table_name(through_klass),
+                                 reflection_foreign_key(reflection.source_reflection),
+                                 through: through_klass)
+          else
+            [::Object.to_s, '']
+          end
+        end
+
+        # @param through [Class, nil]
+        # @return [String]
+        def through_sentence(through = nil)
+          return '' unless through
+
+          " through `#{through}`"
+        end
+
+        # @param table_name [String]
+        # @param foreign_key [String]
+        # @param through [Class, nil]
+        # @return [String]
+        def column_description(table_name, foreign_key, through = nil)
+          return '' if through
+
+          " Database column `#{table_name}.#{foreign_key}`."
+        end
+
+        # @param relation [Symbol, String]
+        # @param klass [Class]
+        # @param table_name [String]
+        # @param foreign_key [String]
+        # @param through [Class, nil]
+        # @return [String]
+        def relation_description(relation, klass, table_name, foreign_key, through = nil)
+          " `#{relation}` relation with `#{klass}`#{through_sentence(through)}.#{column_description(table_name, foreign_key, through)}"
+        end
+
+
+        # @param klass [Class]
+        # @param table_name [String]
+        # @param foreign_key [String]
+        # @param :through [Class, nil]
+        # @return [Array<String>] Type docstring followed by the description of the method.
+        def has_many_description(klass, table_name, foreign_key, through: nil)
+          type_docstring = "Array<#{klass}>"
+          desc = relation_description(:has_many, klass, table_name, foreign_key, through)
+
+          [type_docstring, desc]
+        end
+
+        # @param klass [Class]
+        # @param table_name [String]
+        # @param foreign_key [String]
+        # @param :through [Class, nil]
+        # @return [Array<String>] Type docstring followed by the description of the method.
+        def has_one_description(klass, table_name, foreign_key, through: nil)
+          type_docstring = klass
+          desc = relation_description(:has_one, klass, table_name, foreign_key, through)
+
+          [type_docstring, desc]
+        end
+
+        # @param klass [Class]
+        # @param table_name [String]
+        # @param foreign_key [String]
+        # @return [Array<String>] Type docstring followed by the description of the method.
+        def belongs_to_description(klass, table_name, foreign_key)
+          type_docstring = klass
+          desc = relation_description(:belongs_to, klass, table_name, foreign_key)
+
+          [type_docstring, desc]
+        end
+
         # @param attr_type [ActiveModel::Type::Value]
         # @return [String]
         def yard_type(attr_type)

data/lib/rails/annotate/solargraph/version.rb

@@ -3,7 +3,7 @@
 module Rails
   module Annotate
     module Solargraph
-      VERSION = '0.2.3'
+      VERSION = '0.3.0'
     end
   end
 end

data/rails-annotate-solargraph.gemspec

@@ -16,7 +16,7 @@ Gem::Specification.new do |spec|
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://gitlab.com/mateuszdrewniak/rails-annotate-solargraph"
-  # spec.metadata["changelog_uri"] = "TODO: Put your gem's CHANGELOG.md URL here."
+  spec.metadata["changelog_uri"] = "https://gitlab.com/mateuszdrewniak/rails-annotate-solargraph/-/raw/main/CHANGELOG.md"
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails-annotate-solargraph
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.0
 platform: ruby
 authors:
 - Mateusz Drewniak
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-04-16 00:00:00.000000000 Z
+date: 2022-04-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -67,6 +67,7 @@ licenses:
 metadata:
   homepage_uri: https://gitlab.com/mateuszdrewniak/rails-annotate-solargraph
   source_code_uri: https://gitlab.com/mateuszdrewniak/rails-annotate-solargraph
+  changelog_uri: https://gitlab.com/mateuszdrewniak/rails-annotate-solargraph/-/raw/main/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths: