make_taggable 0.7.4 → 1.0.0

data/lib/make_taggable/taggable/related.rb

@@ -1,11 +1,33 @@
+# frozen_string_literal: true
+
 module MakeTaggable::Taggable
+  ##
+  # Finding records that share tags with this one.
+  #
+  # Results come back ordered by how many tags matched, most first, and carry that figure as a
+  # `count` attribute.
+  #
   module Related
+    ##
+    # @param base [Class] the model being made taggable
+    # @return [void]
+    #
+    # @api private
+    #
     def self.included(base)
       base.extend MakeTaggable::Taggable::Related::ClassMethods
       base.initialize_make_taggable_related
     end
 
+    ##
+    # Added to every taggable model.
+    #
     module ClassMethods
+      ##
+      # Defines `find_related_<context>` and `find_related_<context>_for` for each context.
+      #
+      # @return [void]
+      #
       def initialize_make_taggable_related
         tag_types.map(&:to_s).each do |tag_type|
           class_eval <<-RUBY, __FILE__, __LINE__ + 1
@@ -21,29 +43,70 @@ module MakeTaggable::Taggable
         end
       end
 
+      ##
+      # Adds contexts and refreshes the related-record finders.
+      #
+      # @param args [Array<Symbol, String>] the contexts to add
+      # @return [void]
+      #
       def make_taggable(*args)
-        super(*args)
+        super
         initialize_make_taggable_related
       end
     end
 
+    ##
+    # Records of this model tagged, in one context, with the tags this record carries in another.
+    #
+    # @param search_context [Symbol, String] the context to take this record's tags from
+    # @param result_context [Symbol, String] the context to match them against
+    # @param options [Hash] reserved for future use
+    # @return [ActiveRecord::Relation] ordered by number of matching tags, descending
+    #
     def find_matching_contexts(search_context, result_context, options = {})
       matching_contexts_for(search_context.to_s, result_context.to_s, self.class, options)
     end
 
+    ##
+    # As {#find_matching_contexts}, against another model.
+    #
+    # @param klass [Class] the model to search
+    # @param search_context [Symbol, String] the context to take this record's tags from
+    # @param result_context [Symbol, String] the context to match them against
+    # @param options [Hash] reserved for future use
+    # @return [ActiveRecord::Relation] ordered by number of matching tags, descending
+    #
     def find_matching_contexts_for(klass, search_context, result_context, options = {})
       matching_contexts_for(search_context.to_s, result_context.to_s, klass, options)
     end
 
+    ##
+    # Builds the relation behind {#find_matching_contexts}.
+    #
+    # @param search_context [Symbol, String] the context to take this record's tags from
+    # @param result_context [Symbol, String] the context to match them against
+    # @param klass [Class] the model to search
+    # @param options [Hash] reserved for future use
+    # @return [ActiveRecord::Relation]
+    #
     def matching_contexts_for(search_context, result_context, klass, options = {})
       tags_to_find = tags_on(search_context).map { |t| t.name }
-      related_where(klass, ["#{exclude_self(klass, id)} #{klass.table_name}.#{klass.primary_key} = #{MakeTaggable::Tagging.table_name}.taggable_id AND #{MakeTaggable::Tagging.table_name}.taggable_type = '#{klass.base_class}' AND #{MakeTaggable::Tagging.table_name}.tag_id = #{MakeTaggable::Tag.table_name}.#{MakeTaggable::Tag.primary_key} AND #{MakeTaggable::Tag.table_name}.name IN (?) AND #{MakeTaggable::Tagging.table_name}.context = ?", tags_to_find, result_context])
+      related_where(klass, ["#{exclude_self(klass, id)} #{klass.table_name}.#{klass.primary_key} = #{MakeTaggable::Tagging.table_name}.taggable_id AND #{MakeTaggable::Tagging.table_name}.taggable_type = ? AND #{MakeTaggable::Tagging.table_name}.tag_id = #{MakeTaggable::Tag.table_name}.#{MakeTaggable::Tag.primary_key} AND #{MakeTaggable::Tag.table_name}.name IN (?) AND #{MakeTaggable::Tagging.table_name}.context = ?", klass.base_class.to_s, tags_to_find, result_context])
     end
 
+    ##
+    # Builds the relation behind each generated `find_related_<context>` method.
+    #
+    # @param context [Symbol, String] the context to match on
+    # @param klass [Class] the model to search
+    # @param options [Hash] the search options
+    # @option options [String, Array<String>] :ignore tags to leave out of the match
+    # @return [ActiveRecord::Relation] ordered by number of matching tags, descending
+    #
     def related_tags_for(context, klass, options = {})
       tags_to_ignore = Array.wrap(options[:ignore]).map(&:to_s) || []
       tags_to_find = tags_on(context).map { |t| t.name }.reject { |t| tags_to_ignore.include? t }
-      related_where(klass, ["#{exclude_self(klass, id)} #{klass.table_name}.#{klass.primary_key} = #{MakeTaggable::Tagging.table_name}.taggable_id AND #{MakeTaggable::Tagging.table_name}.taggable_type = '#{klass.base_class}' AND #{MakeTaggable::Tagging.table_name}.tag_id = #{MakeTaggable::Tag.table_name}.#{MakeTaggable::Tag.primary_key} AND #{MakeTaggable::Tag.table_name}.name IN (?) AND #{MakeTaggable::Tagging.table_name}.context = ?", tags_to_find, context])
+      related_where(klass, ["#{exclude_self(klass, id)} #{klass.table_name}.#{klass.primary_key} = #{MakeTaggable::Tagging.table_name}.taggable_id AND #{MakeTaggable::Tagging.table_name}.taggable_type = ? AND #{MakeTaggable::Tagging.table_name}.tag_id = #{MakeTaggable::Tag.table_name}.#{MakeTaggable::Tag.primary_key} AND #{MakeTaggable::Tag.table_name}.name IN (?) AND #{MakeTaggable::Tagging.table_name}.context = ?", klass.base_class.to_s, tags_to_find, context])
     end
 
     private

data/lib/make_taggable/taggable/tag_list_type.rb

@@ -1,4 +1,12 @@
+# frozen_string_literal: true
+
 module MakeTaggable::Taggable
+  ##
+  # The Active Model type backing each generated `*_list` attribute, so tag lists take part in
+  # dirty tracking alongside ordinary columns.
+  #
+  # @api private
+  #
   class TagListType < ActiveModel::Type::Value
   end
 end

data/lib/make_taggable/taggable/tagged_with_query/all_tags_query.rb

@@ -1,5 +1,15 @@
+# frozen_string_literal: true
+
 module MakeTaggable::Taggable::TaggedWithQuery
+  ##
+  # Records carrying every tag in the list.
+  #
+  # @api private
+  #
   class AllTagsQuery < QueryBase
+    ##
+    # @return [ActiveRecord::Relation]
+    #
     def build
       taggable_model.joins(each_tag_in_list)
         .group(by_taggable)

data/lib/make_taggable/taggable/tagged_with_query/any_tags_query.rb

@@ -1,5 +1,15 @@
+# frozen_string_literal: true
+
 module MakeTaggable::Taggable::TaggedWithQuery
+  ##
+  # Records carrying at least one tag in the list.
+  #
+  # @api private
+  #
   class AnyTagsQuery < QueryBase
+    ##
+    # @return [ActiveRecord::Relation]
+    #
     def build
       taggable_model.select(all_fields)
         .where(model_has_at_least_one_tag)

data/lib/make_taggable/taggable/tagged_with_query/exclude_tags_query.rb

@@ -1,5 +1,15 @@
+# frozen_string_literal: true
+
 module MakeTaggable::Taggable::TaggedWithQuery
+  ##
+  # Records carrying none of the tags in the list.
+  #
+  # @api private
+  #
   class ExcludeTagsQuery < QueryBase
+    ##
+    # @return [ActiveRecord::Relation]
+    #
     def build
       taggable_model.joins(owning_to_tagger)
         .where(tags_not_in_list)

data/lib/make_taggable/taggable/tagged_with_query/query_base.rb

@@ -1,5 +1,20 @@
+# frozen_string_literal: true
+
 module MakeTaggable::Taggable::TaggedWithQuery
+  ##
+  # Shared Arel plumbing for the three query strategies.
+  #
+  # @api private
+  #
   class QueryBase
+    ##
+    # @param taggable_model [Class] the model being queried
+    # @param tag_model [Class] the tag model
+    # @param tagging_model [Class] the tagging model
+    # @param tag_list [MakeTaggable::TagList] the tags to match
+    # @param options [Hash] the options given to `tagged_with`
+    # @return [MakeTaggable::Taggable::TaggedWithQuery::QueryBase]
+    #
     def initialize(taggable_model, tag_model, tagging_model, tag_list, options)
       @taggable_model = taggable_model
       @tag_model = tag_model

data/lib/make_taggable/taggable/tagged_with_query.rb

@@ -1,9 +1,26 @@
+# frozen_string_literal: true
+
 require_relative "tagged_with_query/query_base"
 require_relative "tagged_with_query/exclude_tags_query"
 require_relative "tagged_with_query/any_tags_query"
 require_relative "tagged_with_query/all_tags_query"
 
+##
+# Builds the relation behind {MakeTaggable::Taggable::Core::ClassMethods#tagged_with}.
+#
+# @api private
+#
 module MakeTaggable::Taggable::TaggedWithQuery
+  ##
+  # Picks the query strategy the options call for and builds the relation.
+  #
+  # @param taggable_model [Class] the model being queried
+  # @param tag_model [Class] the tag model
+  # @param tagging_model [Class] the tagging model
+  # @param tag_list [MakeTaggable::TagList] the tags to match
+  # @param options [Hash] the options given to `tagged_with`
+  # @return [ActiveRecord::Relation]
+  #
   def self.build(taggable_model, tag_model, tagging_model, tag_list, options)
     if options[:exclude].present?
       ExcludeTagsQuery.new(taggable_model, tag_model, tagging_model, tag_list, options).build

data/lib/make_taggable/taggable.rb

@@ -1,55 +1,61 @@
+# frozen_string_literal: true
+
 module MakeTaggable
+  ##
+  # Declaring a model taggable. Mixed into Active Record automatically, which is what puts
+  # {#make_taggable} on every model.
+  #
   module Taggable
+    ##
+    # Whether this model has been made taggable.
+    #
+    # @return [TrueClass, FalseClass] `false` until {#make_taggable} is called
+    #
     def taggable?
       false
     end
 
     ##
-    # This is an alias for calling <tt>make_taggable :tags</tt>.
+    # Make a model taggable on the given contexts.
     #
-    # Example:
-    #   class Book < ActiveRecord::Base
-    #     acts_as_taggable
-    #   end
-    def acts_as_taggable
-      make_taggable :tags
-    end
-
-    ##
-    # This is an alias for calling <tt>acts_as_ordered_taggable_on :tags</tt>.
+    # Called without arguments it makes the model taggable on `:tags`, which is the context every
+    # other part of the library treats as the default.
     #
-    # Example:
+    # @param tag_types [Array<Symbol, String>] the contexts to tag on
+    # @return [void]
+    #
+    # @example A single, default context
     #   class Book < ActiveRecord::Base
-    #     acts_as_ordered_taggable
+    #     make_taggable
     #   end
-    def acts_as_ordered_taggable
-      acts_as_ordered_taggable_on :tags
-    end
-
-    ##
-    # Make a model taggable on specified contexts.
-    #
-    # @param [Array] tag_types An array of taggable contexts
     #
-    # Example:
+    # @example Several named contexts
     #   class User < ActiveRecord::Base
     #     make_taggable :languages, :skills
     #   end
+    #
     def make_taggable(*tag_types)
+      tag_types = [:tags] if tag_types.flatten.compact.empty?
+
       taggable_on(false, tag_types)
     end
 
     ##
-    # Make a model taggable on specified contexts
-    # and preserves the order in which tags are created
+    # Make a model taggable on the given contexts, preserving the order in which tags were added.
+    #
+    # Called without arguments it makes the model taggable on `:tags`.
     #
-    # @param [Array] tag_types An array of taggable contexts
+    # @param tag_types [Array<Symbol, String>] the contexts to tag on
+    # @return [void]
     #
-    # Example:
+    # @example
     #   class User < ActiveRecord::Base
-    #     acts_as_ordered_taggable_on :languages, :skills
+    #     make_ordered_taggable :languages, :skills
     #   end
-    def acts_as_ordered_taggable_on(*tag_types)
+    #
+    def make_ordered_taggable(*tag_types)
+      tag_types = [:tags] if tag_types.flatten.compact.empty?
+
       taggable_on(true, tag_types)
     end
 
@@ -58,11 +64,6 @@ module MakeTaggable
     # Make a model taggable on specified contexts
     # and optionally preserves the order in which tags are created
     #
-    # Separate methods used above for backwards compatibility
-    # so that the original make_taggable method is unaffected
-    # as it's not possible to add another argument to the method
-    # without the tag_types being enclosed in square brackets
-    #
     # NB: method overridden in core module in order to create tag type
     #     associations and methods after this logic has executed
     #

data/lib/make_taggable/tagger.rb

@@ -1,19 +1,40 @@
+# frozen_string_literal: true
+
 module MakeTaggable
+  ##
+  # Ownership of tags. Mixed into Active Record automatically, which is what puts {ClassMethods#make_tagger}
+  # on every model.
+  #
   module Tagger
+    ##
+    # @param base [Class] the class being extended
+    # @return [void]
+    #
+    # @api private
+    #
     def self.included(base)
       base.extend ClassMethods
     end
 
+    ##
+    # Added to every Active Record model.
+    #
     module ClassMethods
       ##
-      # Make a model a tagger. This allows an instance of a model to claim ownership
-      # of tags.
+      # Make a model a tagger, allowing its instances to claim ownership of the tags they apply.
+      #
+      # Adds an `owned_taggings` association and an `owned_tags` association to the model.
+      #
+      # @param opts [Hash] options forwarded to the generated `owned_taggings` association
+      # @option opts [Proc] :scope a scope applied to the `owned_taggings` association
+      # @return [void]
       #
-      # Example:
+      # @example
       #   class User < ActiveRecord::Base
-      #     acts_as_tagger
+      #     make_tagger
       #   end
-      def acts_as_tagger(opts = {})
+      #
+      def make_tagger(opts = {})
         class_eval do
           owned_taggings_scope = opts.delete(:scope)
 
@@ -34,26 +55,47 @@ module MakeTaggable
         extend MakeTaggable::Tagger::SingletonMethods
       end
 
+      ##
+      # Whether this model claims ownership of the tags it applies.
+      #
+      # @return [TrueClass, FalseClass] `false` until {#make_tagger} is called
+      #
       def tagger?
         false
       end
 
+      ##
+      # @return [TrueClass, FalseClass]
+      # @see #tagger?
+      #
       def is_tagger?
         tagger?
       end
     end
 
+    ##
+    # Added to a model once it is a tagger.
+    #
     module InstanceMethods
       ##
-      # Tag a taggable model with tags that are owned by the tagger.
+      # Tags a record, with this tagger as the owner of the tags.
+      #
+      # The taggable is saved unless `:skip_save` is given, so the tags are persisted immediately.
       #
-      # @param taggable The object that will be tagged
-      # @param [Hash] options An hash with options. Available options are:
-      #               * <tt>:with</tt> - The tags that you want to
-      #               * <tt>:on</tt>   - The context on which you want to tag
+      # @param taggable [ActiveRecord::Base] the record to tag
+      # @param opts [Hash] the tagging options
+      # @option opts [String, Array<String>] :with the tags to apply
+      # @option opts [Symbol, String] :on the context to apply them in
+      # @option opts [TrueClass, FalseClass] :skip_save whether to leave the taggable unsaved
+      # @option opts [TrueClass, FalseClass] :force whether to allow a context the model does not
+      #   declare, on by default
+      # @return [TrueClass, FalseClass] whether the taggable saved, or `false` when it is not taggable
+      # @raise [RuntimeError] when `:on` or `:with` is missing, or the context is undeclared and
+      #   `:force` is off
+      #
+      # @example
+      #   @user.tag(@photo, with: "paris, normandy", on: :locations)
       #
-      # Example:
-      #   @user.tag(@photo, :with => "paris, normandy", :on => :locations)
       def tag(taggable, opts = {})
         opts.reverse_merge!(force: true)
         skip_save = opts.delete(:skip_save)
@@ -67,20 +109,39 @@ module MakeTaggable
         taggable.save unless skip_save
       end
 
+      ##
+      # Whether this record claims ownership of the tags it applies.
+      #
+      # @return [TrueClass, FalseClass]
+      #
       def tagger?
         self.class.is_tagger?
       end
 
+      ##
+      # @return [TrueClass, FalseClass]
+      # @see #tagger?
+      #
       def is_tagger?
         tagger?
       end
     end
 
+    ##
+    # Replaces {ClassMethods#tagger?} once a model is a tagger.
+    #
     module SingletonMethods
+      ##
+      # @return [TrueClass, FalseClass] always `true`
+      #
       def tagger?
         true
       end
 
+      ##
+      # @return [TrueClass, FalseClass]
+      # @see #tagger?
+      #
       def is_tagger?
         tagger?
       end

data/lib/make_taggable/tagging.rb

@@ -1,8 +1,35 @@
+# frozen_string_literal: true
+
 module MakeTaggable
-  class Tagging < ::ActiveRecord::Base #:nodoc:
+  ##
+  # The join between a tag and the record it was applied to.
+  #
+  # A tagging records the context the tag was applied in, and optionally the tagger who applied it.
+  # Records own their taggings, so destroying a taggable destroys its taggings with it.
+  #
+  # @!attribute [rw] context
+  #   The context the tag was applied in, such as `"skills"`.
+  #   @return [String]
+  # @!attribute [rw] tag
+  #   The tag being applied.
+  #   @return [MakeTaggable::Tag]
+  # @!attribute [rw] taggable
+  #   The record being tagged.
+  #   @return [ActiveRecord::Base]
+  # @!attribute [rw] tagger
+  #   The record that applied the tag, when it was applied by a tagger.
+  #   @return [ActiveRecord::Base, NilClass]
+  #
+  class Tagging < ::ActiveRecord::Base
+    ##
+    # The context used when none is given.
+    #
+    # @return [String]
+    #
+    DEFAULT_CONTEXT = "tags"
+
     self.table_name = MakeTaggable.taggings_table
 
-    DEFAULT_CONTEXT = "tags"
     belongs_to :tag, class_name: "::MakeTaggable::Tag", counter_cache: MakeTaggable.tags_counter
     belongs_to :taggable, polymorphic: true
 
@@ -11,7 +38,7 @@ module MakeTaggable
     scope :owned_by, ->(owner) { where(tagger: owner) }
     scope :not_owned, -> { where(tagger_id: nil, tagger_type: nil) }
 
-    scope :by_contexts, ->(contexts) { where(context: (contexts || DEFAULT_CONTEXT)) }
+    scope :by_contexts, ->(contexts) { where(context: contexts || DEFAULT_CONTEXT) }
     scope :by_context, ->(context = DEFAULT_CONTEXT) { by_contexts(context.to_s) }
 
     validates_presence_of :context

data/lib/make_taggable/tags_helper.rb

@@ -1,6 +1,27 @@
+# frozen_string_literal: true
+
 module MakeTaggable
+  ##
+  # View helpers for rendering tags. Mixed into Action View automatically.
+  #
   module TagsHelper
-    # See the wiki for an example using tag_cloud.
+    ##
+    # Yields each tag with the CSS class matching how often it is used, for building a tag cloud.
+    #
+    # Classes are handed out in the order given, from least to most used, so the first class is the
+    # smallest and the last is the largest.
+    #
+    # @param tags [Array<MakeTaggable::Tag>] tags carrying a `taggings_count`
+    # @param classes [Array<String>] the CSS classes, smallest first
+    # @yieldparam tag [MakeTaggable::Tag] the tag
+    # @yieldparam css_class [String] the class for that tag's frequency
+    # @return [Array] the tags, or an empty array when none were given
+    #
+    # @example
+    #   <% tag_cloud(@tags, %w[css1 css2 css3 css4]) do |tag, css_class| %>
+    #     <%= link_to tag.name, tag_path(tag.name), class: css_class %>
+    #   <% end %>
+    #
     def tag_cloud(tags, classes)
       return [] if tags.empty?
 

data/lib/make_taggable/utils.rb

@@ -1,31 +1,66 @@
+# frozen_string_literal: true
+
 module MakeTaggable
+  ##
+  # Database differences the rest of the library needs to work around.
+  #
   module Utils
     class << self
+      ##
+      # The connection tags are read and written through.
+      #
+      # @return [ActiveRecord::ConnectionAdapters::AbstractAdapter]
+      #
       def connection
         MakeTaggable::Tag.connection
       end
 
+      ##
+      # Whether tags are stored in PostgreSQL.
+      #
+      # @return [TrueClass, FalseClass]
+      #
       def using_postgresql?
         connection && connection.adapter_name == "PostgreSQL"
       end
 
+      ##
+      # Whether tags are stored in MySQL.
+      #
+      # @return [TrueClass, FalseClass]
+      #
       def using_mysql?
         connection && connection.adapter_name == "Mysql2"
       end
 
+      ##
+      # A short digest of a string, used to keep generated SQL aliases unique and within the
+      # identifier length databases allow.
+      #
+      # @param string [String] the value to digest
+      # @return [String] the first seven characters of the SHA1 hex digest
+      #
       def sha_prefix(string)
         Digest::SHA1.hexdigest(string)[0..6]
       end
 
+      ##
+      # The case-insensitive pattern operator for the current adapter.
+      #
+      # @return [String] `"ILIKE"` on PostgreSQL, otherwise `"LIKE"`
+      #
       def like_operator
         using_postgresql? ? "ILIKE" : "LIKE"
       end
 
-      def legacy_activerecord?
-        ActiveRecord.version <= Gem::Version.new("5.3.0")
-      end
-
-      # escape _ and % characters in strings, since these are wildcards in SQL.
+      ##
+      # Escapes the SQL pattern wildcards in a string so it matches literally.
+      #
+      # Pair it with an `ESCAPE '!'` clause.
+      #
+      # @param str [String] the value to escape
+      # @return [String] with `!`, `%` and `_` escaped
+      #
       def escape_like(str)
         str.gsub(/[!%_]/) { |x| "!" + x }
       end

data/lib/make_taggable/version.rb

@@ -1,3 +1,10 @@
+# frozen_string_literal: true
+
 module MakeTaggable
-  VERSION = "0.7.4"
+  ##
+  # The released version of the gem.
+  #
+  # @return [String]
+  #
+  VERSION = "1.0.0"
 end