Feature/yard documentation (#85)

* Add yard as a dev dependency, and create a rake task

* add .yardoc to gitignore, remove doc generation

* add .yardoc to gitignore

* remove yard from gemspec, add to base Gemfile

* modify rakefile'

* allow user to specify port

* document configurable public methods with Yard

* finished with content module

* Add documentation to all 'concerns/site'

* accidentally removed collections method

* remove custom cache dir

* fix linting issues

* Fix an issue with return values.

* docs: fix changes discussed in PR review.

* docs: fix linting issue

.gitignore

@@ -28,3 +28,4 @@ bbin/
 */test/dest
 */tmp/*
 .vscode
+.yardoc

Gemfile

@@ -33,7 +33,7 @@ end
 
 group :bridgetown_optional_dependencies do
   gem "mime-types", "~> 3.0"
-  gem "rdoc", "~> 6.0"
+  gem "yard", "~> 0.9"
   gem "tomlrb", "~> 1.2"
   gem "classifier-reborn", "~> 2.2"
   gem "liquid-c", "~> 4.0"

bridgetown-core/Rakefile

@@ -12,3 +12,17 @@ Rake::TestTask.new(:test) do |test|
   test.pattern = "test/**/test_*.rb"
   test.verbose = true
 end
+
+require 'yard'
+YARD::Rake::YardocTask.new(:yard) do |t|
+ t.files   = ['lib/**/*.rb']
+ t.options = ['--no-output']
+ t.stats_options = ['--list-undoc']
+end
+
+namespace :yard do
+  task :serve do
+    port = ENV['YARD_PORT'] || "8808"
+    sh("yard server --reload -p #{port}")
+  end
+end

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

@@ -2,12 +2,17 @@
 
 module Bridgetown
   module Site::Configurable
-    # Public: Set the site's configuration. This handles side-effects caused by
+    # Set the site's configuration. This handles side-effects caused by
     # changing values in the configuration.
     #
-    # config - a Bridgetown::Configuration, containing the new configuration.
+    # @param config [Bridgetown::Configuration]
+    #   An instance of {Bridgetown::Configuration},
+    #   containing the new configuration.
     #
-    # Returns the new configuration.
+    # @return [Bridgetown::Configuration]
+    #   A new instance of {Bridgetown::Configuration}
+    #
+    # @see Bridgetown::Configuration
     def config=(config)
       @config = config.clone
 
@@ -32,81 +37,107 @@ def config=(config)
       @config
     end
 
-    # Returns the FrontmatterDefaults or creates a new FrontmatterDefaults
-    # if it doesn't already exist.
+    # Returns the current instance of {FrontmatterDefaults} or
+    # creates a new instance {FrontmatterDefaults} if it doesn't already exist.
     #
-    # Returns The FrontmatterDefaults
+    # @return [FrontmatterDefaults]
+    #   Returns an instance of {FrontmatterDefaults}
     def frontmatter_defaults
       @frontmatter_defaults ||= FrontmatterDefaults.new(self)
     end
 
-    # Whether to perform a full rebuild without incremental regeneration
+    # Whether to perform a full rebuild without incremental regeneration.
+    # If either +override+["incremental"] or +config+["incremental"] are true,
+    # fully rebuild the site. If not, incrementally build the site.
     #
-    # Returns a Boolean: true for a full rebuild, false for normal build
+    # @param [Hash] override
+    #   An override hash to override the current config value
+    # @option override [Boolean] "incremental" Whether to incrementally build
+    # @return [Boolean] true for full rebuild, false for normal build
     def incremental?(override = {})
       override["incremental"] || config["incremental"]
     end
 
-    # Returns the publisher or creates a new publisher if it doesn't
-    # already exist.
+    # Returns the current instance of {Publisher} or creates a new instance of
+    # {Publisher} if one doesn't exist.
     #
-    # Returns The Publisher
+    # @return [Publisher] Returns an instance of {Publisher}
     def publisher
       @publisher ||= Publisher.new(self)
     end
 
-    # Public: Prefix a given path with the root directory.
+    # Prefix a path or paths with the {#root_dir} directory.
     #
-    # paths - (optional) path elements to a file or directory within the
-    #         root directory
+    # @see Bridgetown.sanitized_path
+    # @param paths [Array<String>]
+    #   An array of paths to prefix with the root_dir directory using the
+    #   {Bridgetown.sanitized_path} method.
     #
-    # Returns a path which is prefixed with the root_dir directory.
+    # @return [Array<String>] Return an array of updated paths if multiple paths given.
     def in_root_dir(*paths)
       paths.reduce(root_dir) do |base, path|
         Bridgetown.sanitized_path(base, path)
       end
     end
 
-    # Public: Prefix a given path with the source directory.
-    #
-    # paths - (optional) path elements to a file or directory within the
-    #         source directory
+    # Prefix a path or paths with the {#source} directory.
     #
-    # Returns a path which is prefixed with the source directory.
+    # @see Bridgetown.sanitized_path
+    # @param paths [Array<String>]
+    #   An array of paths to prefix with the source directory using the
+    #   {Bridgetown.sanitized_path} method.
+    # @return [Array<String>] Return an array of updated paths if multiple paths given.
     def in_source_dir(*paths)
       paths.reduce(source) do |base, path|
         Bridgetown.sanitized_path(base, path)
       end
     end
 
-    # Public: Prefix a given path with the destination directory.
+    # Prefix a path or paths with the {#dest} directory.
     #
-    # paths - (optional) path elements to a file or directory within the
-    #         destination directory
+    # @see Bridgetown.sanitized_path
+    # @param paths [Array<String>]
+    #   An array of paths to prefix with the destination directory using the
+    #   {Bridgetown.sanitized_path} method.
     #
-    # Returns a path which is prefixed with the destination directory.
+    # @return [Array<String>] Return an array of updated paths if multiple paths given.
     def in_dest_dir(*paths)
       paths.reduce(dest) do |base, path|
         Bridgetown.sanitized_path(base, path)
       end
     end
 
-    # Public: Prefix a given path with the cache directory.
+    # Prefix a path or paths with the {#cache_dir} directory.
     #
-    # paths - (optional) path elements to a file or directory within the
-    #         cache directory
+    # @see Bridgetown.sanitized_path
+    # @param paths [Array<String>]
+    #   An array of paths to prefix with the {#cache_dir} directory using the
+    #   {Bridgetown.sanitized_path} method.
     #
-    # Returns a path which is prefixed with the cache directory.
+    # @return [Array<String>] Return an array of updated paths if multiple paths given.
     def in_cache_dir(*paths)
       paths.reduce(cache_dir) do |base, path|
         Bridgetown.sanitized_path(base, path)
       end
     end
 
-    # Public: The full path to the directory that houses all the collections registered
-    # with the current site.
+    # The full path to the directory that houses all the registered collections
+    # for the current site.
+    #
+    # If +@collections_path+ is specified use its value.
+    #
+    # If +@collections+ is not specified and +config+["collections_dir"] is
+    # specified, prepend it with {#source} and assign it to
+    # {#collections_path}.
+    #
+    # If +@collections+ is not specified and +config+["collections_dir"] is not
+    # specified, assign {#source} to +@collections_path+
     #
-    # Returns the source directory or the absolute path to the custom collections_dir
+    # @return [String] Returns the full path to the collections directory
+    # @see #config
+    # @see #source
+    # @see #collections_path
+    # @see #in_source_dir
     def collections_path
       dir_str = config["collections_dir"]
       @collections_path ||= dir_str.empty? ? source : in_source_dir(dir_str)

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

@@ -4,17 +4,24 @@ module Bridgetown
   module Site::Content
     # Construct a Hash of Posts indexed by the specified Post attribute.
     #
-    # post_attr - The String name of the Post attribute.
+    # @param post_attr [String] The String name of the Post attribute.
     #
-    # Examples
+    # @example
+    #   Returns a hash like so: { attr => posts } where
+    #
+    #   attr  - One of the values for the requested attribute.
+    #
+    #   posts - The Array of Posts with the given attr value.
+    #
+    # @example
     #
     #   post_attr_hash('categories')
     #   # => { 'tech' => [<Post A>, <Post B>],
     #   #      'ruby' => [<Post B>] }
     #
-    # Returns the Hash: { attr => posts } where
-    #   attr  - One of the values for the requested attribute.
-    #   posts - The Array of Posts with the given attr value.
+    # @return [Hash{String, Symbol => Array<Post>}]
+    #   Returns a hash of !{attr => posts}
+    #
     def post_attr_hash(post_attr)
       # Build a hash map based on the specified post attribute ( post attr =>
       # array of posts ) then sort each array in reverse order.
@@ -28,41 +35,85 @@ def post_attr_hash(post_attr)
       end
     end
 
+    # Returns a hash of "tags" using {#post_attr_hash} where each tag is a key
+    # and each value is a post which contains the key.
+    # @example
+    #   tags
+    #   # => { 'tech': [<Post A>, <Post B>],
+    #   #      'ruby': [<Post C> }
+    # @return [Hash{String, Array<Post>}] Returns a hash of all tags and their corresponding posts
+    # @see post_attr_hash
     def tags
       post_attr_hash("tags")
     end
 
+    # Returns a hash of "categories" using {#post_attr_hash} where each tag is
+    # a key and each value is a post which contains the key.
+    # @example
+    #   categories
+    #   # => { 'tech': [<Post A>, <Post B>],
+    #   #      'ruby': [<Post C> }
+    # @return [Hash{String, Array<Post>}] Returns a hash of all categories and
+    #   their corresponding posts
+    # @see post_attr_hash
     def categories
       post_attr_hash("categories")
     end
 
+    # Returns the value of +data+["site_metadata"] or creates a new instance of
+    # +ActiveSupport::HashWithIndifferentAccess+
+    # @return [Hash] Returns a hash of site metadata
     def metadata
       data["site_metadata"] ||= ActiveSupport::HashWithIndifferentAccess.new
     end
 
     # The Hash payload containing site-wide data.
     #
-    # Returns the Hash: { "site" => data } where data is a Hash with keys:
-    #   "time"       - The Time as specified in the configuration or the
-    #                  current time if none was specified.
-    #   "posts"      - The Array of Posts, sorted chronologically by post date
-    #                  and then title.
-    #   "pages"      - The Array of all Pages.
-    #   "html_pages" - The Array of HTML Pages.
-    #   "categories" - The Hash of category values and Posts.
-    #                  See Site#post_attr_hash for type info.
-    #   "tags"       - The Hash of tag values and Posts.
-    #                  See Site#post_attr_hash for type info.
+    # @example
+    #   site_payload
+    #   # => { "site" => data } Where data is a Hash. See example below
+    #
+    #   site = site_payload["site"]
+    #   # => Returns a Hash with the following keys:
+    #   #
+    #   # site["time"]       - The Time as specified in the configuration or the
+    #   #                      current time if none was specified.
+    #   #
+    #   # site["posts"]      - The Array of Posts, sorted chronologically by post date
+    #   #                      and then title.
+    #   #
+    #   # site["pages"]      - The Array of all Pages.
+    #   #
+    #   # site["html_pages"] - The Array of HTML Pages.
+    #   #
+    #   # site["categories"] - The Hash of category values and Posts.
+    #   #                      See Site#post_attr_hash for type info.
+    #   #
+    #   # site["tags"]       - The Hash of tag values and Posts.
+    #   #                      See Site#post_attr_hash for type info.
+    #
+    # @return [Hash] Returns a hash in the structure of { "site" => data }
+    #
+    #   See above example for usage.
+    #
+    # @see #post_attr_hash
     def site_payload
       Drops::UnifiedPayloadDrop.new self
     end
     alias_method :to_liquid, :site_payload
 
-    # The list of collections and their corresponding Bridgetown::Collection instances.
-    # If config['collections'] is set, a new instance is created
-    # for each item in the collection, a new hash is returned otherwise.
+    # The list of {#collections} and their corresponding {Bridgetown::Collection} instances.
+    #
+    # If +config+['collections'] is set, a new instance of {Bridgetown::Collection} is created
+    # for each entry in the collections configuration.
+    #
+    # If +config+["collections"] is not specified, a blank hash is returned.
     #
-    # Returns a Hash containing collection name-to-instance pairs.
+    # @return [Hash{String, Symbol => Bridgetown::Collection}] A Hash
+    #   containing a collection name-to-instance pairs.
+    #
+    # @return [Hash] Returns a blank hash if no items found
+    # @see Collection
     def collections
       @collections ||= collection_names.each_with_object(
         ActiveSupport::HashWithIndifferentAccess.new
@@ -71,10 +122,11 @@ def collections
       end
     end
 
-    # The list of collection names.
-    #
-    # Returns an array of collection names from the configuration,
-    #   or an empty array if the `collections` key is not set.
+    # An array of collection names.
+    # @return [Array<Collection>] an array of collection names from the configuration,
+    #   or an empty array if the +config+["collections"] key is not set.
+    # @raise ArgumentError Raise an error if +config+["collections"] is not
+    #   an Array or a Hash
     def collection_names
       case config["collections"]
       when Hash
@@ -88,22 +140,29 @@ def collection_names
       end
     end
 
-    # Get all the documents
-    #
-    # Returns an Array of all Documents
+    # Get all documents.
+    # @return [Array<String>] an array of documents from the configuration
     def documents
       collections.each_with_object(Set.new) do |(_, collection), set|
         set.merge(collection.docs).merge(collection.files)
       end.to_a
     end
 
-    # Get the to be written documents
+    # Get the documents to be written
     #
-    # Returns an Array of Documents which should be written
+    # @return [Array<String, File>] an Array of Documents which should be written and
+    #   that +respond_to :write?+
+    # @see #documents
+    # @see Collection
     def docs_to_write
       documents.select(&:write?)
     end
 
+    # Get all posts.
+    #
+    # @return [Collection] A #Collection of posts. Returns +#collections+["posts"]
+    # @return [Collection] Return a new #Collection if +#collections+["posts"] is nil
+    # @see Collection
     def posts
       collections["posts"] ||= Collection.new(self, "posts")
     end