Convert a large number of comment docs to YARD (#932)

* convert a large number of comment docs to YARD

* cop fix

* Add style overrides for YARD

* Add SF Mono to the list

* More style improvements

* remove tests for removed deprecated post_url Liquid tag behavior

* Finish converting doc comments to YARD

.yardopts

@@ -1,4 +1,7 @@
 bridgetown-core/lib/**/*.rb
 bridgetown-builder/lib/**/*.rb
+bridgetown-foundation/lib/**/*.rb
 bridgetown-paginate/lib/**/*.rb
+bridgetown-routes/lib/**/*.rb
 -m markdown
+-p yard/templates

bridgetown-builder/lib/bridgetown-builder/dsl/generators.rb

@@ -4,6 +4,10 @@ module Bridgetown
   module Builders
     module DSL
       module Generators
+        # Set up a new generator based on the block or method provided which will run alongside
+        # other generators during the build process
+        #
+        # @param method_name [Symbol] use a Builder method rather than a block to run
         def generator(method_name = nil, &block)
           block = method(method_name) if method_name.is_a?(Symbol)
           local_name = name # pull the name method into a local variable

bridgetown-builder/lib/bridgetown-builder/dsl/helpers.rb

@@ -5,9 +5,15 @@ module Builders
     module DSL
       module Helpers
         def helpers
-          @helpers # could be nil
+          @helpers # could be nil. gets set once a helper method is actually called
         end
 
+        # Define a helper for use in view templates, alongside built-in helpers, using either a
+        # builder method or a block
+        #
+        # @param helper_name [Symbol] name of the helper
+        # @param method_name [Symbol] name of a Builder method to use, if block isn't provided
+        #   and the method is named different from the helper
         def helper(helper_name, method_name = nil, &block)
           m = Module.new
 

bridgetown-builder/lib/bridgetown-builder/dsl/hooks.rb

@@ -4,6 +4,13 @@ module Bridgetown
   module Builders
     module DSL
       module Hooks
+        # Define a hook to run at some point during the build process
+        #
+        # @param owner [Symbol] name of the owner (`:site`, `:resource`, etc.)
+        # @param event [Symbol] name of the event (`:pre_read`, `:post_render`, etc.)
+        # @param method_name [Symbol] name of a Builder method to use, if block isn't provided
+        # @param priority [Integer, Symbol] either `:low`, `:normal`, or `:high`, or an integer.
+        #   Default is normal (20)
         def hook(
           owner,
           event,
@@ -17,9 +24,13 @@ def hook(
           functions << { name:, hook: [owner, event, priority, hook_block] }
         end
 
+        # Define a site post_read hook and add data returned by the block to the site data/signals
         def add_data(data_key)
           hook(:site, :post_read) do
-            site.data[data_key] = yield
+            yield.tap do |value|
+              site.data[data_key] = value
+              site.signals[data_key] = value
+            end
           end
         end
       end

bridgetown-core/lib/bridgetown-core/cache.rb

@@ -33,8 +33,6 @@ def clear
 
       # Compare the current config to the cached config
       # If they are different, clear all caches
-      #
-      # Returns nothing.
       def clear_if_config_changed(config)
         config = config.inspect
         cache = Bridgetown::Cache.new "Bridgetown::Cache"
@@ -49,8 +47,6 @@ def clear_if_config_changed(config)
       private
 
       # Delete all cached items from all caches
-      #
-      # Returns nothing.
       def delete_cache_files
         FileUtils.rm_rf(@cache_dir) if disk_cache_enabled
       end
@@ -60,9 +56,7 @@ def delete_cache_files
 
     # Get an existing named cache, or create a new one if none exists
     #
-    # name - name of the cache
-    #
-    # Returns nothing.
+    # @param name [String] name of the cache
     def initialize(name)
       @cache = Bridgetown::Cache.base_cache[name] ||= {}
       @name = name.gsub(%r![^\w\s-]!, "-")
@@ -77,7 +71,7 @@ def clear
     # Retrieve a cached item
     # Raises if key does not exist in cache
     #
-    # Returns cached value
+    # @return [Object] cached value
     def [](key)
       return @cache[key] if @cache.key?(key)
 
@@ -88,8 +82,6 @@ def [](key)
     end
 
     # Add an item to cache
-    #
-    # Returns nothing.
     def []=(key, value)
       @cache[key] = value
       return unless disk_cache_enabled?
@@ -112,16 +104,14 @@ def getset(key)
     end
 
     # Remove one particular item from the cache
-    #
-    # Returns nothing.
     def delete(key)
       @cache.delete(key)
       File.delete(path_to(hash(key))) if disk_cache_enabled?
     end
 
     # Check if `key` already exists in this cache
     #
-    # Returns true if key exists in the cache, false otherwise
+    # @return [Boolean] true if key exists in the cache, false otherwise
     def key?(key)
       # First, check if item is already cached in memory
       return true if @cache.key?(key)
@@ -153,14 +143,11 @@ def hash(key)
     end
 
     # Remove all this caches items from disk
-    #
-    # Returns nothing.
     def delete_cache_files
       FileUtils.rm_rf(path_to) if disk_cache_enabled?
     end
 
     # Load `path` from disk and return the result.
-    # This MUST NEVER be called in Safe Mode
     # rubocop:disable Security/MarshalLoad
     def load(path)
       raise unless disk_cache_enabled?
@@ -173,9 +160,6 @@ def load(path)
     # rubocop:enable Security/MarshalLoad
 
     # Given a path and a value, save value to disk at path.
-    # This should NEVER be called in Safe Mode
-    #
-    # Returns nothing.
     def dump(path, value)
       return unless disk_cache_enabled?
 

bridgetown-core/lib/bridgetown-core/cleaner.rb

@@ -17,20 +17,19 @@ def cleanup!
 
     private
 
-    # Private: The list of files and directories to be deleted during cleanup process
+    # The list of files and directories to be deleted during cleanup process
     #
-    # Returns an Array of the file and directory paths
+    # @return [Array<String>] file and directory paths
     def obsolete_files
       out = (existing_files - new_files - new_dirs + replaced_files).to_a
       Bridgetown::Hooks.trigger :clean, :on_obsolete, out
       @new_files = @new_dirs = nil
       out
     end
 
-    # Private: The list of existing files, apart from those included in
-    # keep_files and hidden files.
+    # The list of existing files, apart from those included in keep_files and hidden files
     #
-    # Returns a Set with the file paths
+    # @return [Set<String>] file paths
     def existing_files
       files = Set.new
       regex = keep_file_regex
@@ -45,9 +44,9 @@ def existing_files
       files
     end
 
-    # Private: The list of files to be created when site is built.
+    # The list of files to be created when site is built.
     #
-    # Returns a Set with the file paths
+    # @return [Set<String>] file paths
     def new_files
       @new_files ||= Set.new.tap do |files|
         site.each_site_file do |item|
@@ -60,17 +59,17 @@ def new_files
       end
     end
 
-    # Private: The list of directories to be created when site is built.
+    # The list of directories to be created when site is built.
     # These are the parent directories of the files in #new_files.
     #
-    # Returns a Set with the directory paths
+    # @return [Set<String>] directory paths
     def new_dirs
       @new_dirs ||= new_files.flat_map { |file| parent_dirs(file) }.to_set
     end
 
-    # Private: The list of parent directories of a given file
+    # The list of parent directories of a given file
     #
-    # Returns an Array with the directory paths
+    # @return [Array<String>] directory paths
     def parent_dirs(file)
       parent_dir = File.dirname(file)
       if parent_dir == site.dest
@@ -80,29 +79,28 @@ def parent_dirs(file)
       end
     end
 
-    # Private: The list of existing files that will be replaced by a directory
-    # during build
+    # The list of existing files that will be replaced by a directory during build
     #
-    # Returns a Set with the file paths
+    # @return [Set<String>] file paths
     def replaced_files
       new_dirs.select { |dir| File.file?(dir) }.to_set
     end
 
-    # Private: The list of directories that need to be kept because they are
+    # The list of directories that need to be kept because they are
     # parent directories of files specified in keep_files
     #
-    # Returns a Set with the directory paths
+    # @return [Set<String>] directory paths
     def keep_dirs
       site.config.keep_files.flat_map { |file| parent_dirs(site.in_dest_dir(file)) }.to_set
     end
 
-    # Private: Creates a regular expression from the config's keep_files array
+    # Creates a regular expression from the config's keep_files array
     #
-    # Examples
+    # @example
     #   ['.git','.svn'] with site.dest "/myblog/_site" creates
     #   the following regex: /\A\/myblog\/_site\/(\.git|\/.svn)/
     #
-    # Returns the regular expression
+    # @return [Regexp]
     def keep_file_regex
       %r!\A#{Regexp.quote(site.dest)}/(#{Regexp.union(site.config.keep_files).source})!
     end

bridgetown-core/lib/bridgetown-core/commands/build.rb

@@ -79,11 +79,9 @@ def build
 
       protected
 
-      # Build your Bridgetown site.
+      # Build your Bridgetown site
       #
-      # options - A Hash of options passed to the command or loaded from config
-      #
-      # Returns nothing.
+      # @param options [Bridgetown::Configuration] options loaded from config and/or CLI
       def build_site(config_options)
         t = Time.now
         display_folder_paths(config_options)
@@ -97,20 +95,16 @@ def build_site(config_options)
                                           "#{(Time.now - t).ceil(2)} seconds."
       end
 
-      # Watch for file changes and rebuild the site.
-      #
-      # options - A Hash of options passed to the command or loaded from config
+      # Watch for file changes and rebuild the site
       #
-      # Returns nothing.
+      # @param options [Bridgetown::Configuration] options loaded from config and/or CLI
       def watch_site(config_options)
         Bridgetown::Watcher.watch(@site, config_options)
       end
 
       # Display the source and destination folder paths
       #
-      # options - A Hash of options passed to the command
-      #
-      # Returns nothing.
+      # @param options [Bridgetown::Configuration] options loaded from config and/or CLI
       def display_folder_paths(config_options)
         source = File.expand_path(config_options["source"])
         destination = File.expand_path(config_options["destination"])

bridgetown-core/lib/bridgetown-core/component.rb

@@ -94,7 +94,7 @@ def supported_template_extensions
 
       def path_for_errors
         File.basename(component_template_path)
-      rescue RuntimeError
+      rescue RuntimeError, TypeError
         source_location
       end
     end

bridgetown-core/lib/bridgetown-core/concerns/layout_placeable.rb

@@ -4,7 +4,7 @@ module Bridgetown
   module LayoutPlaceable
     # Determine whether the file should be placed into layouts.
     #
-    # Returns false if the document is an asset file or if the front matter
+    # @return [Boolean] false if the document is an asset file or if the front matter
     #   specifies `layout: none`
     def place_in_layout?
       no_layout?.!

bridgetown-core/lib/bridgetown-core/concerns/publishable.rb

@@ -3,6 +3,8 @@
 module Bridgetown
   module Publishable
     # Whether the resource is published or not, as indicated in YAML front-matter
+    #
+    # @return [Boolean]
     def published?
       !(data.key?("published") && data["published"] == false)
     end

bridgetown-core/lib/bridgetown-core/concerns/site/content.rb

@@ -27,6 +27,7 @@ def categories
     end
 
     # Returns the contents of the site metadata file or a blank hash
+    #
     # @return [HashWithDotAccess::Hash] Returns a hash of site metadata
     def metadata
       signals["site_metadata"] ||= HashWithDotAccess::Hash.new
@@ -49,7 +50,6 @@ def site_payload
     #
     # @return [HashWithDotAccess::Hash{String, Symbol => Collection}] A Hash
     #   containing a collection name-to-instance pairs.
-    #
     # @return [HashWithDotAccess::Hash] Returns a blank hash if no items found
     def collections
       @collections ||= collection_names.each_with_object(
@@ -60,6 +60,7 @@ def collections
     end
 
     # An array of collection names.
+    #
     # @return [Array<String>] an array of collection names from the configuration,
     #   or an empty array if the `config["collections"]` key is not set.
     def collection_names
@@ -84,6 +85,7 @@ def taxonomy_types
     end
 
     # Get all loaded resources.
+    #
     # @return [Array<Bridgetown::Resource::Base>] an array of resources
     def resources
       collections.each_with_object(Set.new) do |(_, collection), set|
@@ -112,6 +114,7 @@ def add_generated_page(generated_page)
     end
 
     # Loads and memoizes the parsed frontend bundler manifest file (if available)
+    #
     # @return [Hash]
     def frontend_manifest
       @frontend_manifest ||= begin

bridgetown-core/lib/bridgetown-core/concerns/site/extensible.rb

@@ -4,6 +4,7 @@ class Bridgetown::Site
   module Extensible
     # Load necessary libraries, plugins, converters, and generators.
     # This is only ever run once for the lifecycle of the site object.
+    #
     # @see Converter
     # @see Generator
     # @see PluginManager
@@ -16,6 +17,7 @@ def setup
     end
 
     # Run all Generators.
+    #
     # @see Generator
     # @return [void]
     def generate
@@ -34,6 +36,7 @@ def generate
     end
 
     # Get the implementation for the given Converter class.
+    #
     # @param klass [Class] The Class of the Converter to fetch.
     # @return [Converter] Returns the {Converter}
     #   instance implementing the given `Converter` class.
@@ -46,7 +49,8 @@ def find_converter_instance(klass)
 
     # Create an array of instances of the subclasses of the class
     #   passed in as argument.
-    # @param klass [Class] - class which is the parent of the subclasses.
+    #
+    # @param klass [Class] class which is the parent of the subclasses.
     # @return [Array<Converter, Generator>] Returns an array of instances of
     #   subclasses of `klass`.
     def instantiate_subclasses(klass)
@@ -56,6 +60,7 @@ def instantiate_subclasses(klass)
     end
 
     # Shorthand for registering a site hook via {Bridgetown::Hooks}
+    #
     # @param event [Symbol] name of the event (`:pre_read`, `:post_render`, etc.)
     # @yield the block will be called when the event is triggered
     # @yieldparam site the site which triggered the event hook