Merge pull request #576 from olleolleolle/fix/docs-for-api

Options#print_options + API docs for Options, Parser

lib/github_changelog_generator/generator/generator.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-require_relative "../octo_fetcher"
-require_relative "generator_generation"
-require_relative "generator_fetcher"
-require_relative "generator_processor"
-require_relative "generator_tags"
+require "github_changelog_generator/octo_fetcher"
+require "github_changelog_generator/generator/generator_generation"
+require "github_changelog_generator/generator/generator_fetcher"
+require "github_changelog_generator/generator/generator_processor"
+require "github_changelog_generator/generator/generator_tags"
 
 module GitHubChangelogGenerator
   # Default error for ChangelogGenerator

lib/github_changelog_generator/options.rb

@@ -1,10 +1,17 @@
 # frozen_string_literal: true
 
 require "delegate"
+require "github_changelog_generator/helper"
+
 module GitHubChangelogGenerator
+  # This class wraps Options, and knows a list of known options. Others options
+  # will raise exceptions.
   class Options < SimpleDelegator
+    # Raised on intializing with unknown keys in the values hash,
+    # and when trying to store a value on an unknown key.
     UnsupportedOptionError = Class.new(ArgumentError)
 
+    # List of valid option names
     KNOWN_OPTIONS = %i[
       add_issues_wo_labels
       add_pr_wo_labels
@@ -56,33 +63,56 @@ module GitHubChangelogGenerator
       verbose
     ]
 
+    # @param values [Hash]
+    #
+    # @raise [UnsupportedOptionError] if given values contain unknown options
     def initialize(values)
       super(values)
       unsupported_options.any? && raise(UnsupportedOptionError, unsupported_options.inspect)
     end
 
+    # Set option key to val.
+    #
+    # @param key [Symbol]
+    # @param val [Object]
+    #
+    # @raise [UnsupportedOptionError] when trying to set an unknown option
     def []=(key, val)
       supported_option?(key) || raise(UnsupportedOptionError, key.inspect)
       values[key] = val
     end
 
+    # @return [Hash]
     def to_hash
       values
     end
 
     # Loads the configured Ruby files from the --require option.
-    #
-    # @return [void]
     def load_custom_ruby_files
       self[:require].each { |f| require f }
     end
 
+    # Pretty-prints a censored options hash, if :verbose.
+    def print_options
+      return unless self[:verbose]
+      Helper.log.info "Using these options:"
+      pp(censored_values)
+      puts ""
+    end
+
     private
 
     def values
       __getobj__
     end
 
+    # Returns a censored options hash.
+    #
+    # @return [Hash] The GitHub `:token` key is censored in the output.
+    def censored_values
+      values.clone.tap { |opts| opts[:token] = opts[:token].nil? ? "No token used" : "hidden value" }
+    end
+
     def unsupported_options
       values.keys - KNOWN_OPTIONS
     end

lib/github_changelog_generator/parser.rb

@@ -3,8 +3,9 @@
 
 require "optparse"
 require "pp"
-require_relative "version"
-require_relative "helper"
+require "github_changelog_generator/version"
+require "github_changelog_generator/helper"
+
 module GitHubChangelogGenerator
   class Parser
     # parse options with optparse
@@ -21,30 +22,17 @@ module GitHubChangelogGenerator
 
       abort(parser.banner) unless options[:user] && options[:project]
 
-      print_options(options)
+      options.print_options
 
       options
     end
 
-    # If options set to verbose, print the parsed options.
+    # Setup parsing options
     #
-    # The GitHub `:token` key is censored in the output.
-    #
-    # @param options [Hash] The options to display
-    # @option options [Boolean] :verbose If false this method does nothing
-    def self.print_options(options)
-      if options[:verbose]
-        Helper.log.info "Performing task with options:"
-        options_to_display = options.clone
-        options_to_display[:token] = options_to_display[:token].nil? ? nil : "hidden value"
-        pp options_to_display
-        puts ""
-      end
-    end
-
-    # setup parsing options
+    # @param options [Options]
+    # @return [OptionParser]
     def self.setup_parser(options)
-      parser = OptionParser.new do |opts| # rubocop:disable Metrics/BlockLength
+      OptionParser.new do |opts| # rubocop:disable Metrics/BlockLength
         opts.banner = "Usage: github_changelog_generator [options]"
         opts.on("-u", "--user [USER]", "Username of the owner of target GitHub repo") do |last|
           options[:user] = last
@@ -196,10 +184,9 @@ module GitHubChangelogGenerator
           exit
         end
       end
-      parser
     end
 
-    # @return [Hash] Default options
+    # @return [Options] Default options
     def self.default_options
       Options.new(
         date_format: "%Y-%m-%d",