bridgetown-core 2.0.0.beta2 → 2.0.0.beta4

data/lib/bridgetown-core/filters/date_filters.rb

@@ -8,12 +8,11 @@ module Bridgetown
       # (e.g. "27th Jan 2011") and US ("e.g. Jan 27th, 2011") formats.
       # UK format is the default.
       #
-      # date - the Time to format.
-      # type - if "ordinal" the returned String will be in ordinal format
-      # style - if "US" the returned String will be in US format.
-      #         Otherwise it will be in UK format.
-      #
-      # Returns the formatting String.
+      # @param date [Time]
+      # @param type [String] if "ordinal" the returned String will be in ordinal format
+      # @param style [String] if "US" the returned String will be in US format.
+      #   Otherwise it will be in UK format.
+      # @return [String]
       def date_to_string(date, type = nil, style = nil)
         stringify_date(date, "%b", type, style)
       end
@@ -23,42 +22,29 @@ module Bridgetown
       # (e.g. "27th January 2011") and US ("e.g. January 27th, 2011") formats.
       # UK format is the default.
       #
-      # date - the Time to format.
-      # type - if "ordinal" the returned String will be in ordinal format
-      # style - if "US" the returned String will be in US format.
-      #         Otherwise it will be in UK format.
-      #
-      # Returns the formatted String.
+      # @param date [Time]
+      # @param type [String] if "ordinal" the returned String will be in ordinal format
+      # @param style [String] if "US" the returned String will be in US format.
+      #   Otherwise it will be in UK format.
+      # @return [String]
       def date_to_long_string(date, type = nil, style = nil)
         stringify_date(date, "%B", type, style)
       end
 
-      # Format a date for use in XML.
-      #
-      # date - The Time to format.
-      #
-      # Examples
-      #
-      #   date_to_xmlschema(Time.now)
-      #   # => "2011-04-24T20:34:46+08:00"
+      # Format a date for use in XML, e.g. "2011-04-24T20:34:46+08:00"
       #
-      # Returns the formatted String.
+      # @param date [Time]
+      # @return [String]
       def date_to_xmlschema(date)
         return date if date.to_s.empty?
 
         time(date).xmlschema
       end
 
-      # Format a date according to RFC-822
+      # Format a date according to RFC-822, e.g. "Sun, 24 Apr 2011 12:34:46 +0000"
       #
-      # date - The Time to format.
-      #
-      # Examples
-      #
-      #   date_to_rfc822(Time.now)
-      #   # => "Sun, 24 Apr 2011 12:34:46 +0000"
-      #
-      # Returns the formatted String.
+      # @param date [Time]
+      # @return [String]
       def date_to_rfc822(date)
         return date if date.to_s.empty?
 
@@ -67,11 +53,12 @@ module Bridgetown
 
       private
 
-      # month_type: Notations that evaluate to 'Month' via `Time#strftime` ("%b", "%B")
-      # type: nil (default) or "ordinal"
-      # style: nil (default) or "US"
-      #
-      # Returns a stringified date or the empty input.
+      # @param date [Time]
+      # @param month_type [String] notations that evaluate to 'Month' via `Time#strftime`
+      #   ("%b", "%B")
+      # @param type [String]
+      # @param style [String]
+      # @return [String]
       def stringify_date(date, month_type, type = nil, style = nil)
         return date if date.to_s.empty?
 

data/lib/bridgetown-core/filters/grouping_filters.rb

@@ -3,14 +3,15 @@
 module Bridgetown
   module Filters
     module GroupingFilters
-      # Group an array of items by a property
+      # Group an array of items by a property, returning an array of hashes
       #
-      # input - the inputted Enumerable
-      # property - the property
+      # @example
+      #   {"name"  => "larry"
+      #    "items" => [...] } # all the items where `property` == "larry"
       #
-      # Returns an array of Hashes, each looking something like this:
-      #  {"name"  => "larry"
-      #   "items" => [...] } # all the items where `property` == "larry"
+      # @param input [Enumerable]
+      # @param property [String]
+      # @return [Array<Hash>]
       def group_by(input, property)
         if groupable?(input)
           groups = input.group_by { |item| item_property(item, property).to_s }
@@ -22,11 +23,10 @@ module Bridgetown
 
       # Group an array of items by an expression
       #
-      # input - the object array
-      # variable - the variable to assign each item to in the expression
-      # expression -a Liquid comparison expression passed in as a string
-      #
-      # Returns the filtered array of objects
+      # @param input [Enumerable]
+      # @param variable [String] variable to assign each item to in the expression
+      # @param expression [String] Liquid comparison expression
+      # @return [Array<Hash>]
       def group_by_exp(input, variable, expression)
         return input unless groupable?(input)
 

data/lib/bridgetown-core/filters.rb

@@ -11,33 +11,30 @@ module Bridgetown
     include TranslationFilters
     include ConditionHelpers
 
-    # Convert a Markdown string into HTML output.
+    # Convert a Markdown string into HTML output
     #
-    # input - The Markdown String to convert.
-    #
-    # Returns the HTML formatted String.
+    # @param input [String]
+    # @return [String] HTML formatted text
     def markdownify(input)
       @context.registers[:site].find_converter_instance(
         Bridgetown::Converters::Markdown
       ).convert(input.to_s)
     end
 
-    # Convert quotes into smart quotes.
-    #
-    # input - The String to convert.
+    # Convert quotes into smart quotes
     #
-    # Returns the smart-quotified String.
+    # @param input [String]
+    # @return [String] smart-quotified text
     def smartify(input)
       Utils::SmartyPantsConverter.new(@context.registers[:site].config).convert(input.to_s)
     end
 
-    # Slugify a filename or title.
-    #
-    # input - The filename or title to slugify.
-    # mode - how string is slugified
+    # Slugify a filename or title
     #
-    # Returns the given filename or title as a lowercase URL String.
-    # See Utils.slugify for more detail.
+    # @param input [String] the filename or title to slugify
+    # @param mode [String] how string is slugified
+    # @see Utils.slugify
+    # @return [String] lowercase URL
     def slugify(input, mode = nil)
       mode = @context.registers[:site].config.slugify_mode if mode.nil?
       Utils.slugify(input, mode:)
@@ -45,10 +42,9 @@ module Bridgetown
 
     # Titleize a slug or identifier string.
     #
-    # input - The string to titleize.
-    #
-    # Returns a transformed string with spaces and capitalized words.
-    # See Utils.titleize_slug for more detail.
+    # @param input [String]
+    # @see Utils.titleize_slug for more detail
+    # @return [String] transformed string with spaces and capitalized words
     def titleize(input)
       Utils.titleize_slug(input)
     end
@@ -56,13 +52,12 @@ module Bridgetown
     # XML escape a string for use. Replaces any special characters with
     # appropriate HTML entity replacements.
     #
-    # Examples
-    #
+    # @example
     #   xml_escape('foo "bar" <baz>')
     #   # => "foo &quot;bar&quot; &lt;baz&gt;"
     #
-    # @param input [String] The String to escape.
-    # @return [String] the escaped String.
+    # @param input [String]
+    # @return [String]
     def xml_escape(input)
       Utils.xml_escape(input)
     end
@@ -70,28 +65,24 @@ module Bridgetown
     # CGI escape a string for use in a URL. Replaces any special characters
     # with appropriate %XX replacements.
     #
-    # input - The String to escape.
-    #
-    # Examples
-    #
+    # @example
     #   cgi_escape('foo,bar;baz?')
     #   # => "foo%2Cbar%3Bbaz%3F"
     #
-    # Returns the escaped String.
+    # @param input [String]
+    # @return [String]
     def cgi_escape(input)
       CGI.escape(input.to_s)
     end
 
     # URI escape a string.
     #
-    # input - The String to escape.
-    #
-    # Examples
-    #
+    # @example
     #   uri_escape('foo, bar \\baz?')
     #   # => "foo,%20bar%20%5Cbaz?"
     #
-    # Returns the escaped String.
+    # @param input [String]
+    # @return [String]
     def uri_escape(input)
       Addressable::URI.normalize_component(input)
     end
@@ -113,23 +104,22 @@ module Bridgetown
 
     # Replace any whitespace in the input string with a single space
     #
-    # input - The String on which to operate.
-    #
-    # Returns the formatted String
+    # @param input [String]
+    # @return [String]
     def normalize_whitespace(input)
       input.to_s.gsub(%r!\s+!, " ").strip
     end
 
     # Count the number of words in the input string.
     #
-    # input - The String on which to operate.
-    #
-    # Returns the Integer word count.
+    # @param input [String]
+    # @return [Integer] word count
     def number_of_words(input)
       input.split.length
     end
 
-    # Calculates the average reading time of the supplied content.
+    # Calculates the average reading time of the supplied content
+    #
     # @param input [String] the String of content to analyze.
     # @return [Float] the number of minutes required to read the content.
     def reading_time(input, round_to = 0)
@@ -138,17 +128,15 @@ module Bridgetown
     end
 
     # Join an array of things into a string by separating with commas and the
-    # word "and" for the last one.
-    #
-    # array - The Array of Strings to join.
-    # connector - Word used to connect the last 2 items in the array
-    #
-    # Examples
+    # word "and" for the last one
     #
+    # @example
     #   array_to_sentence_string(["apples", "oranges", "grapes"])
     #   # => "apples, oranges, and grapes"
     #
-    # Returns the formatted String.
+    # @param array [Array<String>]
+    # @param connector [String] word used to connect the last 2 items in the array
+    # @return [String]
     def array_to_sentence_string(array, connector = "and")
       case array.length
       when 0
@@ -162,24 +150,20 @@ module Bridgetown
       end
     end
 
-    # Convert the input into json string
-    #
-    # input - The Array or Hash to be converted
+    # Convert the input into JSON string
     #
-    # Returns the converted json string
+    # @param input [Array, Hash, String, Integer]
+    # @return [String] JSON string
     def jsonify(input)
       as_liquid(input).to_json
     end
 
-    # Filter an array of objects
+    # Filter an array of objects or a hash (will use values)
     #
-    # input    - the object array.
-    # property - the property within each object to filter by.
-    # value    - the desired value.
-    #            Cannot be an instance of Array nor Hash since calling #to_s on them returns
-    #            their `#inspect` string object.
-    #
-    # Returns the filtered array of objects
+    # @param input [Array, Hash]
+    # @param property [String] the property within each object to filter by
+    # @param value [String] value for the search
+    # @return [Array] filtered array of objects
     def where(input, property, value) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       return input if !property || value.is_a?(Array) || value.is_a?(Hash)
       return input unless input.respond_to?(:select)
@@ -201,15 +185,14 @@ module Bridgetown
 
     # Filters an array of objects against an expression
     #
-    # input - the object array
-    # variable - the variable to assign each item to in the expression
-    # expression - a Liquid comparison expression passed in as a string
-    #
-    # Returns the filtered array of objects
+    # @param input [Array, Hash]
+    # @param variable [String] the variable to assign each item to in the expression
+    # @param expression [String] a Liquid comparison expression passed in as a string
+    # @return [Array] filtered array of objects
     def where_exp(input, variable, expression)
       return input unless input.respond_to?(:select)
 
-      input = input.values if input.is_a?(Hash) # FIXME
+      input = input.values if input.is_a?(Hash)
 
       condition = parse_condition(expression)
       @context.stack do
@@ -222,9 +205,8 @@ module Bridgetown
 
     # Convert the input into integer
     #
-    # input - the object string
-    #
-    # Returns the integer value
+    # @param input [String, Boolean] if boolean, 1 for true and 0 for false
+    # @return [Integer]
     def to_integer(input)
       return 1 if input == true
       return 0 if input == false
@@ -234,11 +216,10 @@ module Bridgetown
 
     # Sort an array of objects
     #
-    # input - the object array
-    # property - property within each object to filter by
-    # nils ('first' | 'last') - nils appear before or after non-nil values
-    #
-    # Returns the filtered array of objects
+    # @param input [Array]
+    # @param property [String] the property within each object to filter by
+    # @param nils [String] `first` | `last` (nils appear before or after non-nil values)
+    # @return [Array] sorted array of objects
     def sort(input, property = nil, nils = "first")
       raise ArgumentError, "Cannot sort a null object." if input.nil?
 

data/lib/bridgetown-core/front_matter/defaults.rb

@@ -5,6 +5,8 @@ module Bridgetown
     # This class handles custom defaults for front matter settings.
     # It is exposed via the frontmatter_defaults method on the site class.
     class Defaults
+      using Bridgetown::Refinements
+
       # @return [Bridgetown::Site]
       attr_reader :site
 
@@ -16,6 +18,7 @@ module Bridgetown
       def reset
         @glob_cache = {}
         @defaults_cache = {}
+        @sets = nil
       end
 
       def ensure_time!(set)
@@ -33,7 +36,6 @@ module Bridgetown
       #
       # @param path [String] the relative path of the resource
       # @param collection_name [Symbol] :posts, :pages, etc.
-      #
       # @return [Hash] all default values (an empty hash if there are none)
       def all(path, collection_name)
         if @defaults_cache.key?([path, collection_name])
@@ -70,11 +72,10 @@ module Bridgetown
 
       # Checks if a given default setting scope matches the given path and collection
       #
-      # scope - the hash indicating the scope, as defined in bridgetown.config.yml
-      # path - the path to check for
-      # collection - the collection (:posts or :pages) to check for
-      #
-      # Returns true if the scope applies to the given collection and path
+      # @param scope [Hash] the scope as defined in site configuration
+      # @param path [String] the path to check for
+      # @param collection [Symbol] the collection (:posts, :pages, etc.) to check for
+      # @return [Boolean] true if the scope applies to the given collection and path
       def applies?(scope, path, collection)
         applies_collection?(scope, collection) && applies_path?(scope, path)
       end
@@ -129,7 +130,6 @@ module Bridgetown
       #
       # @param scope [Hash] the defaults set being asked about
       # @param collection [Symbol] the collection of the resource being processed
-      #
       # @return [Boolean] whether either of the above conditions are satisfied
       def applies_collection?(scope, collection)
         !scope.key?("collection") || scope["collection"].eql?(collection.to_s)
@@ -137,8 +137,7 @@ module Bridgetown
 
       # Checks if a given set of default values is valid
       #
-      # @param set [Hash] the default value hash as defined in bridgetown.config.yml
-      #
+      # @param set [Hash] the default value hash as defined in site configuration
       # @return [Boolean] if the set is valid and can be used
       def valid?(set)
         set.is_a?(Hash) && set["values"].is_a?(Hash)
@@ -146,10 +145,9 @@ module Bridgetown
 
       # Determines if a new scope has precedence over an old one
       #
-      # old_scope - the old scope hash, or nil if there's none
-      # new_scope - the new scope hash
-      #
-      # Returns true if the new scope has precedence over the older
+      # @param old_scope [Hash] old scope hash, or nil if there's none
+      # @param new_scope [Hash] new scope hash
+      # @return [Boolean] true if the new scope has precedence over the older
       # rubocop: disable Naming/PredicateName
       def has_precedence?(old_scope, new_scope)
         return true if old_scope.nil?
@@ -180,15 +178,12 @@ module Bridgetown
 
       # Returns a list of valid sets
       #
-      # This is not cached to allow plugins to modify the configuration
-      # and have their changes take effect
-      #
       # @return [Array<Hash>]
       def valid_sets
-        sets = site.config["defaults"]
-        return [] unless sets.is_a?(Array)
+        @sets ||= site.config["defaults"].map(&:as_dots)
+        return [] unless @sets.is_a?(Array)
 
-        sets.filter_map do |set|
+        @sets.filter_map do |set|
           if valid?(set)
             massage_scope!(set)
             # TODO: is this trip really necessary?

data/lib/bridgetown-core/generated_page.rb

@@ -25,13 +25,13 @@ module Bridgetown
       .htm
     ).freeze
 
-    # Initialize a new GeneratedPage.
+    # Initialize a new GeneratedPage
     #
-    # site - The Site object.
-    # base - The String path to the source.
-    # dir  - The String path between the source and the file.
-    # name - The String filename of the file.
-    # from_plugin - true if the Page file is located in a Gem-based plugin folder
+    # @param site [Bridgetown::Site]
+    # @param base [String] path to the source
+    # @param dir [String] path between the source and the file
+    # @param name [String] filename of the file.
+    # @param from_plugin [Boolean] true if the Page file is located in a Gem-based plugin folder
     # rubocop:disable Metrics/ParameterLists
     def initialize(site, base, dir, name, from_plugin: false)
       @site = site

data/lib/bridgetown-core/generators/prototype_generator.rb

@@ -76,7 +76,6 @@ module Bridgetown
     # Check incoming prototype configuration and normalize options.
     #
     # @param prototype_page [Bridgetown::GeneratedPage, Bridgetown::Resource::Base]
-    #
     # @return [String, nil]
     def validate_search_term(prototype_page)
       # @type [String]
@@ -108,7 +107,6 @@ module Bridgetown
     # Provide a list of all relevent indexed values for the given term.
     #
     # @param search_term [String]
-    #
     # @return [Array<String>]
     def terms_matching_pages(search_term)
       pages_list = site.collections[@configured_collection].resources

data/lib/bridgetown-core/helpers.rb

@@ -11,7 +11,7 @@ module Bridgetown
       include ::Streamlined::Helpers
       include Inclusive
 
-      # @return [Bridgetown::RubyTemplateView]
+      # @return [Bridgetown::RubyTemplateView, Bridgetown::Component]
       attr_reader :view
 
       # @return [Bridgetown::Site]
@@ -22,7 +22,7 @@ module Bridgetown
       # @return [Bridgetown::Foundation::SafeTranslations]
       packages def translate_package = [Bridgetown::Foundation::Packages::SafeTranslations]
 
-      # @param view [Bridgetown::RubyTemplateView]
+      # @param view [Bridgetown::RubyTemplateView, Bridgetown::Component]
       # @param site [Bridgetown::Site]
       def initialize(view = nil, site = nil)
         @view = view

data/lib/bridgetown-core/hooks.rb

@@ -25,7 +25,6 @@ module Bridgetown
 
     @registry = {}
 
-    NotAvailable = Class.new(RuntimeError)
     Uncallable = Class.new(RuntimeError)
 
     def self.priority_value(priority)

data/lib/bridgetown-core/layout.rb

@@ -95,11 +95,10 @@ module Bridgetown
       content || ""
     end
 
-    # Accessor for data properties by Liquid.
+    # Accessor for data properties by Liquid
     #
-    # property - The String name of the property to retrieve.
-    #
-    # Returns the String value or nil if the property isn't included.
+    # @param property [String] name of the property to retrieve
+    # @return [String, nil] value or nil if the property isn't included
     def [](property)
       data[property]
     end

data/lib/bridgetown-core/liquid_extensions.rb

@@ -4,11 +4,9 @@ module Bridgetown
   module LiquidExtensions
     # Lookup a Liquid variable in the given context.
     #
-    # context  - the Liquid context in question.
-    # variable - the variable name, as a string.
-    #
-    # Returns the value of the variable in the context
-    #   or the variable name if not found.
+    # @param context [Liquid::Context]
+    # @param variable [String] the variable name
+    # @return [Object] value of the variable in the context or the variable name if not found
     def lookup_variable(context, variable)
       lookup = context