bridgetown-core 2.0.0.beta2 → 2.0.0.beta3

data/lib/bridgetown-core/concerns/site/renderable.rb

@@ -3,6 +3,7 @@
 class Bridgetown::Site
   module Renderable
     # Render all pages & documents so they're ready to be written out to disk.
+    #
     # @return [void]
     # @see Page
     # @see Document
@@ -97,6 +98,7 @@ class Bridgetown::Site
     end
 
     # Renders all resources
+    #
     # @return [void]
     def render_resources
       collections.each_value do |collection|
@@ -109,6 +111,7 @@ class Bridgetown::Site
     end
 
     # Renders a content item while ensuring site locale is set if the data is available.
+    #
     # @param item [Bridgetown::Resource::Base] The item to render
     # @yield Runs the block in between locale setting and resetting
     # @return [void]

data/lib/bridgetown-core/concerns/site/ssr.rb

@@ -45,7 +45,6 @@ class Bridgetown::Site
     end
 
     def ssr_first_read
-      # TODO: this shouldn't be running twice, right?!
       Bridgetown::Hooks.trigger :site, :pre_read, self
       defaults_reader.tap do |d|
         d.path_defaults.clear

data/lib/bridgetown-core/configuration.rb

@@ -111,12 +111,11 @@ module Bridgetown
     attr_writer :source_manifests, :roda_initializers
 
     class << self
-      # Static: Produce a Configuration ready for use in a Site.
+      # Produce a Configuration ready for use in a Site.
       # It takes the input, fills in the defaults where values do not exist.
       #
-      # user_config - a Hash or Configuration of overrides.
-      #
-      # Returns a Configuration filled with defaults.
+      # @param user_config [Hash, Configuration]
+      # @return [Configuration] filled with defaults
       def from(user_config, starting_defaults = DEFAULTS)
         Utils.deep_merge_hashes(starting_defaults.deep_dup, Configuration.new(user_config))
           .merge_environment_specific_options!
@@ -177,16 +176,14 @@ module Bridgetown
     # Directory of the top-level root where config files are located
     #
     # @param override [Hash] options hash which will override value if key is present
-    #
     # @return [String] path to the Bridgetown root directory
     def root_dir(override = {})
       get_config_value_with_override("root_dir", override)
     end
 
-    # Public: Directory of the Bridgetown source folder
+    # Directory of the Bridgetown source folder
     #
     # @param override [Hash] options hash which will override value if key is present
-    #
     # @return [String]  path to the Bridgetown source directory
     def source(override = {})
       get_config_value_with_override("source", override)
@@ -208,11 +205,10 @@ module Bridgetown
       raise "Unable to parse `#{File.basename(filename)}'. #{e.message}"
     end
 
-    # Public: Generate list of configuration files from the override
+    # Generate list of configuration files from the override
     #
-    # override - the command-line options hash
-    #
-    # Returns an Array of config files
+    # @param override [Hash] the command-line options hash
+    # @return [Array<string>] config files
     def config_files(override)
       # Adjust verbosity quickly
       Bridgetown.logger.adjust_verbosity(
@@ -232,9 +228,8 @@ module Bridgetown
     # Read in a list of configuration files and merge with this hash
     #
     # @param files [Array<String>]
-    #
     # @return [Hash] configuration with the defaults overridden by the values in the
-    # configuration files
+    #   configuration files
     def read_config_files(files)
       config = self
 
@@ -257,7 +252,6 @@ module Bridgetown
     # Read configuration and return merged Hash
     #
     # @param file [String] the path to the YAML file to be read in
-    #
     # @return [Hash]
     def read_config_file(file)
       default_config_file = file == "bridgetown.config.yml"

data/lib/bridgetown-core/converter.rb

@@ -40,7 +40,6 @@ module Bridgetown
     #
     # @param content [String] content of file (without front matter).
     # @param convertible [Bridgetown::Layout, Bridgetown::Resource::Base]
-    #
     # @return [String] the converted content.
     def convert(content, convertible = nil) # rubocop:disable Lint/UnusedMethodArgument
       content
@@ -48,10 +47,8 @@ module Bridgetown
 
     # Does the given extension match this converter's list of acceptable extensions?
     #
-    # @param [String] ext
-    #   The file's extension (including the dot)
+    # @param ext [String] the file's extension (including the dot)
     # @param convertible [Bridgetown::Layout, Bridgetown::Resource::Base]
-    #
     # @return [Boolean] Whether the extension matches one in the list
     def matches(ext, _convertible = nil)
       (self.class.extname_list || []).include?(ext.downcase)
@@ -67,9 +64,7 @@ module Bridgetown
     # You can override this in Converter subclasses as needed. Default is ".html", unless the
     # converter is a template engine and the input file doesn't match the normal template extension
     #
-    # @param [String] ext
-    #   The extension of the original file
-    #
+    # @param ext [String] the extension of the original file
     # @return [String] The output file extension (including the dot)
     def output_ext(ext)
       if self.class.template_engine

data/lib/bridgetown-core/converters/identity.rb

@@ -9,21 +9,13 @@ module Bridgetown
 
       support_slots
 
-      # Public: Does the given extension match this converter's list of acceptable extensions?
-      # Takes one argument: the file's extension (including the dot).
-      #
-      # _ext - The String extension to check (not relevant here)
-      #
-      # Returns true since it always matches.
+      # @return [Boolean] true since it always matches.
       def matches(*)
         true
       end
 
-      # Public: The extension to be given to the output file (including the dot).
-      #
-      # ext - The String extension or original file.
-      #
-      # Returns The String output file extension.
+      # @param ext [String] the extension of the original file
+      # @return [String] The output file extension (including the dot)
       def output_ext(ext)
         ext
       end

data/lib/bridgetown-core/converters/liquid_templates.rb

@@ -22,7 +22,6 @@ module Bridgetown
       # @param convertible [
       #   Bridgetown::GeneratedPage, Bridgetown::Resource::Base, Bridgetown::Layout]
       #   The instantiated object which is processing the file.
-      #
       # @return [String] The converted content.
       def convert(content, convertible)
         self.class.cached_partials ||= {}
@@ -55,17 +54,16 @@ module Bridgetown
       # rubocop: enable Metrics/MethodLength
       # rubocop: enable Metrics/AbcSize
 
-      # Fetches the payload used in Liquid rendering.
-      # Falls back to site.site_payload if no payload is set.
+      # Fetches the payload used in Liquid rendering, aka `site.site_payload`
       #
-      # Returns a Bridgetown::Drops::UnifiedPayloadDrop
+      # @return [Bridgetown::Drops::UnifiedPayloadDrop]
       def payload
         @payload ||= site.site_payload
       end
 
       # Set page content to payload and assign paginator if document has one.
       #
-      # Returns nothing
+      # @return [void]
       def configure_payload(content = nil)
         payload["page"] = document.to_liquid
         payload["paginator"] = document.respond_to?(:paginator) ? document.paginator.to_liquid : nil

data/lib/bridgetown-core/converters/markdown/kramdown_parser.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Kramdown
-  # A Kramdown::Document subclass meant to optimize memory usage from initializing
+  # A `Kramdown::Document`` subclass meant to optimize memory usage from initializing
   # a kramdown document for parsing.
   #
   # The optimization is by using the same options Hash (and its derivatives) for

data/lib/bridgetown-core/converters/markdown.rb

@@ -43,26 +43,25 @@ module Bridgetown
       end
       # rubocop:enable Naming/AccessorMethodName
 
-      # Public: Provides you with a list of processors comprised of the ones we support internally
+      # Provides you with a list of processors comprised of the ones we support internally
       # and the ones that you have provided to us
       #
-      # Returns an array of symbols.
+      # @return [Array<Symbol>]
       def valid_processors
         [:kramdown] + third_party_processors
       end
 
-      # Public: A list of processors that you provide via plugins.
+      # A list of processors that you provide via plugins
       #
-      # Returns an array of symbols
+      # @return [Array<Symbol>]
       def third_party_processors
         self.class.constants - [:KramdownParser, :PRIORITIES]
       end
 
-      # Logic to do the content conversion.
+      # Logic to do the content conversion
       #
-      # content - String content of file (without front matter).
-      #
-      # Returns a String of the converted content.
+      # @param content [String] content of file (without front matter)
+      # @return [String] converted content
       def convert(content, convertible = nil)
         setup
         if @cache
@@ -85,13 +84,11 @@ module Bridgetown
         self.class.const_get(converter_name).new(@config) if custom_class_allowed?(converter_name)
       end
 
-      # Private: Determine whether a class name is an allowed custom
-      #   markdown class name.
-      #
-      # parser_name - the name of the parser class
+      # Determine whether a class name is an allowed custom markdown class name.
       #
-      # Returns true if the parser name contains only alphanumeric characters and is defined
-      # within Bridgetown::Converters::Markdown
+      # @param parser_name [Symbol] name of the parser class
+      # @return [Boolean] true if the parser name contains only alphanumeric characters and is
+      #   defined within `Bridgetown::Converters::Markdown`
       def custom_class_allowed?(parser_name)
         parser_name !~ %r![^A-Za-z0-9_]! && self.class.constants.include?(parser_name.to_sym)
       end

data/lib/bridgetown-core/converters/serbea_templates.rb

@@ -25,14 +25,13 @@ module Bridgetown
       template_engine :serbea
       input :serb
 
-      # Logic to do the Serbea content conversion.
+      # Logic to do the Serbea content conversion
       #
-      # @param content [String] Content of the file (without front matter).
+      # @param content [String] Content of the file (without front matter)
       # @param convertible [
       #   Bridgetown::GeneratedPage, Bridgetown::Resource::Base, Bridgetown::Layout]
       #   The instantiated object which is processing the file.
-      #
-      # @return [String] The converted content.
+      # @return [String] The converted content
       def convert(content, convertible)
         serb_view = Bridgetown::SerbeaView.new(convertible)
         serb_renderer = Tilt::SerbeaTemplate.new(

data/lib/bridgetown-core/drops/drop.rb

@@ -11,23 +11,22 @@ module Bridgetown
       # Mutability determines whether or not pre-defined fields may be
       # overwritten.
       #
-      # is_mutable - Boolean set mutability of the class (default: nil)
+      # @param is_mutable [Boolean] set mutability of the class
       #
-      # Returns the mutability of the class
+      # @return [Boolean] the mutability of the class
       def self.mutable(is_mutable = nil)
         @is_mutable = is_mutable || false
       end
 
+      # @return [Boolean] the mutability of the class
       def self.mutable?
         @is_mutable
       end
 
       # Create a new Drop
       #
-      # obj - the Bridgetown Site, Collection, or Resource required by the
+      # @param obj [Object] the Bridgetown Site, Collection, or Resource required by the
       # drop.
-      #
-      # Returns nothing
       def initialize(obj) # rubocop:disable Lint/MissingSuper
         @obj = obj
       end
@@ -37,9 +36,8 @@ module Bridgetown
       # and finally check the underlying hash (e.g. document front matter)
       # if all the previous places didn't match.
       #
-      # key - the string key whose value to fetch
-      #
-      # Returns the value for the given key, or nil if none exists
+      # @param key [String] key whose value to fetch
+      # @return [Object, nil] returns the value for the given key if present
       def [](key)
         if self.class.mutable? && mutations.key?(key)
           mutations[key]
@@ -51,26 +49,22 @@ module Bridgetown
       end
       alias_method :invoke_drop, :[]
 
-      # Set a field in the Drop. If mutable, sets in the mutations and
-      # returns. If not mutable, checks first if it's trying to override a
-      # Drop method and raises a DropMutationException if so. If not
-      # mutable and the key is not a method on the Drop, then it sets the
-      # key to the value in the underlying hash (e.g. document front
-      # matter)
+      # Set a field in the Drop. If mutable, sets in the mutations and returns. If not mutable,
+      # checks first if it's trying to override a Drop method and raises an exception if so.
+      # If not mutable and the key is not a method on the Drop, then it sets the key to the value
+      # in the underlying hash (e.g. document front matter)
       #
-      # key - the String key whose value to set
-      # val - the Object to set the key's value to
-      #
-      # Returns the value the key was set to unless the Drop is not mutable
-      # and the key matches a method in which case it raises a
-      # DropMutationException.
+      # @param key [String] key whose value to set
+      # @param val [Object] what to set the key's value to
+      # @return [Object] the value the key was set to unless the Drop is not mutable
+      #   and the key matches a method in which case it raises an exception
       def []=(key, val)
         setter = "#{key}="
         if respond_to?(setter)
           public_send(setter, val)
         elsif respond_to?(key.to_s)
           unless self.class.mutable?
-            raise Errors::DropMutationException, "Key #{key} cannot be set in the drop."
+            raise Errors::FatalException, "Key #{key} cannot be set in the drop."
           end
 
           mutations[key] = val
@@ -82,7 +76,7 @@ module Bridgetown
       # Generates a list of strings which correspond to content getter
       # methods.
       #
-      # Returns an Array of strings which represent method-specific keys.
+      # @return [Array<String>] method-specific keys
       def content_methods
         @content_methods ||= (
           self.class.instance_methods \
@@ -95,9 +89,8 @@ module Bridgetown
 
       # Check if key exists in Drop
       #
-      # key - the string key whose value to fetch
-      #
-      # Returns true if the given key is present
+      # @param key [String] key whose value to set
+      # @return [Boolean] true if the given key is present
       def key?(key)
         return false if key.nil?
         return true if self.class.mutable? && mutations.key?(key)
@@ -121,7 +114,7 @@ module Bridgetown
       # value. It includes Drop methods, mutations, and the underlying object's
       # data. See the documentation for Drop#keys for more.
       #
-      # Returns a Hash with all the keys and values resolved.
+      # @return [Hash<String, Object>] all the keys and values resolved
       def to_h
         keys.each_with_object({}) do |(key, _), result|
           result[key] = self[key]
@@ -132,33 +125,27 @@ module Bridgetown
       # Inspect the drop's keys and values through a JSON representation
       # of its keys and values.
       #
-      # Returns a pretty generation of the hash representation of the Drop.
+      # @return [String]
       def inspect
         JSON.pretty_generate to_h
       end
 
-      # Generate a Hash for use in generating JSON.
-      # This is useful if fields need to be cleared before the JSON can generate.
+      # Generate a Hash for use in generating JSON. Essentially an alias for `to_h`
       #
-      # Returns a Hash ready for JSON generation.
+      # @return [Hash<String, Object>] all the keys and values resolved
       def hash_for_json(*)
         to_h
       end
 
-      # Generate a JSON representation of the Drop.
+      # Generate a JSON representation of the Drop
       #
-      # state - the JSON::State object which determines the state of current processing.
-      #
-      # Returns a JSON representation of the Drop in a String.
+      # @param state [JSON::State] object which determines the state of current processing
+      # @return [String] JSON representation of the Drop
       def to_json(state = nil)
         JSON.generate(hash_for_json(state), state)
       end
 
-      # Collects all the keys and passes each to the block in turn.
-      #
-      # block - a block which accepts one argument, the key
-      #
-      # Returns nothing.
+      # Collects all the keys and passes each to the block in turn
       def each_key(&)
         keys.each(&)
       end
@@ -194,10 +181,10 @@ module Bridgetown
         end
       end
 
-      # Imitate Hash.fetch method in Drop
+      # Imitate `Hash.fetch` method in Drop
       #
-      # Returns value if key is present in Drop, otherwise returns default value
-      # KeyError is raised if key is not present and no default value given
+      # @return [Object] value if key is present in Drop, otherwise returns default value.
+      #   KeyError is raised if key is not present and no default value given
       def fetch(key, default = nil, &block)
         return self[key] if key?(key)
         raise KeyError, %(key not found: "#{key}") if default.nil? && block.nil?

data/lib/bridgetown-core/drops/resource_drop.rb

@@ -58,9 +58,8 @@ module Bridgetown
       # Generate a Hash for use in generating JSON.
       # This is useful if fields need to be cleared before the JSON can generate.
       #
-      # state - the JSON::State object which determines the state of current processing.
-      #
-      # Returns a Hash ready for JSON generation.
+      # @param state [JSON::State] object which determines the state of current processing
+      # @return [Hash<String, Object>] all the keys and values resolved
       def hash_for_json(state = nil)
         to_h.tap do |hash|
           # use collection label in the hash
@@ -76,19 +75,13 @@ module Bridgetown
       # Generate a Hash which breaks the recursive chain.
       # Certain fields which are normally available are omitted.
       #
-      # Returns a Hash with only non-recursive fields present.
+      # @return [Hash<String, Object>] only non-recursive fields present
       def collapse_document(doc)
         doc.keys.each_with_object({}) do |(key, _), result|
           result[key] = doc[key] unless NESTED_OBJECT_FIELD_BLACKLIST.include?(key)
         end
       end
 
-      # Generates a list of keys with user content as their values.
-      # This gathers up the Drop methods and keys of the mutations and
-      # underlying data hashes and performs a set union to ensure a list
-      # of unique keys for the Drop.
-      #
-      # @return [Array<String>]
       def keys
         keys_to_remove = %w[next_resource previous_resource]
         (content_methods |
@@ -98,8 +91,6 @@ module Bridgetown
         end
       end
 
-      # Inspect the drop's keys and values through a JSON representation
-      # of its keys and values.
       def inspect
         JSON.pretty_generate hash_for_json
       end

data/lib/bridgetown-core/errors.rb

@@ -4,16 +4,10 @@ module Bridgetown
   module Errors
     FatalException = Class.new(::RuntimeError)
 
-    DropMutationException       = Class.new(FatalException)
-    InvalidPermalinkError       = Class.new(FatalException)
-    InvalidYAMLFrontMatterError = Class.new(FatalException)
-    MissingDependencyException  = Class.new(FatalException)
-
+    InvalidConfigurationError   = Class.new(FatalException)
     InvalidDateError            = Class.new(FatalException)
-    InvalidPostNameError        = Class.new(FatalException)
+    InvalidYAMLFrontMatterError = Class.new(FatalException)
     PostURLError                = Class.new(FatalException)
-    InvalidURLError             = Class.new(FatalException)
-    InvalidConfigurationError   = Class.new(FatalException)
 
     def self.print_build_error(exc, trace: false, logger: Bridgetown.logger, server: false) # rubocop:todo Metrics
       logger.error "Exception raised:", exc.class.to_s.bold

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

@@ -2,10 +2,9 @@
 
 module Bridgetown
   module Filters
+    # The following set of code was *adapted* from `Liquid::If`
+    # ref: https://git.io/vp6K6
     module ConditionHelpers
-      # -----------   The following set of code was *adapted* from Liquid::If
-      # -----------   ref: https://git.io/vp6K6
-
       # Parse a string to a Liquid Condition
       def parse_condition(exp)
         parser    = Liquid::Parser.new(exp)
@@ -19,9 +18,8 @@ module Bridgetown
       # the parsed expression based on whether the expression consists of binary operations with
       # Liquid operators `and` or `or`
       #
-      #  - parser: an instance of Liquid::Parser
-      #
-      # Returns an instance of Liquid::Condition
+      # @param parser [Liquid::Parser]
+      # @return [Liquid::Condition]
       def parse_binary_comparison(parser)
         condition = parse_comparison(parser)
         first_condition = condition
@@ -37,9 +35,8 @@ module Bridgetown
       # on whether the parsed expression involves a "comparison" operator
       # (e.g. <, ==, >, !=, etc)
       #
-      #  - parser: an instance of Liquid::Parser
-      #
-      # Returns an instance of Liquid::Condition
+      # @param parser [Liquid::Parser]
+      # @return [Liquid::Condition]
       def parse_comparison(parser)
         left_operand = Liquid::Expression.parse(parser.expression)
         operator     = parser.consume?(:comparison)

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)