how_is.rb in how_is-18.0.0

- old
+ new

@@ -14,69 +14,97 @@
   require 'how_is/report'
 
   DEFAULT_FORMAT = :html
 
   ##
-  # Generate a report file.
-  def self.generate_report_file(report:, **kw_args)
-    analysis = self.generate_analysis(**kw_args)
-
-    Report.export_file(analysis, report)
-  end
-
-  ##
-  # Generates and returns a report as a String.
+  # Generate a HowIs instance, so you can generate reports.
+  #
+  # @param repository [String] The name of a GitHub repository (of the
+  #   format <user or organization>/<repository>).
+  # @param analysis [HowIs::Analysis] Optional; if passed, this Analysis
+  #   object is used instead of generating one.
   def initialize(repository, analysis = nil, **kw_args)
+    # If no Analysis is passed, generate one.
     analysis ||= HowIs.generate_analysis(repository: repository, **kw_args)
+
+    # Used by to_html, to_json, etc.
     @analysis = analysis
   end
 
+  ##
+  # Generate an HTML report.
+  #
+  # @returns [String] An HTML report.
   def to_html
     Report.export(@analysis, :html)
   end
 
+  ##
+  # Generate a JSON report.
+  #
+  # @returns [String] A JSON report.
   def to_json
     Report.export(@analysis, :json)
   end
 
+  ##
+  # Given a JSON report, create a new HowIs object (for generating other
+  # reports).
+  #
+  # @param json [String] A JSON report object.
+  # @returns [HowIs] A HowIs object that can be used for generating other
+  #   reports, treating the JSON report as a cache.
   def self.from_json(json)
-    analysis = HowIs::Analyzer.from_json(json)
+    self.from_hash(JSON.parse(json))
+  end
 
+  ##
+  # Given report data as a hash, create a new HowIs object (for generating
+  # other reports).
+  #
+  # @param data [Hash] A hash containing report data.
+  # @returns [HowIs] A HowIs object that can be used for generating other
+  #   reports, treating the provided report data as a cache.
+  def self.from_hash(data)
+    analysis = HowIs::Analyzer.from_hash(data)
+
     self.new(analysis.repository, analysis)
   end
 
   ##
   # Returns a list of possible export formats.
+  #
+  # @returns [Array<String>] An array of the types of reports you can
+  #   generate.
   def self.supported_formats
     report_constants = HowIs.constants.grep(/.Report/) - [:BaseReport]
     report_constants.map {|x| x.to_s.split('Report').first.downcase }
   end
 
   ##
   # Returns whether or not the specified +file+ can be exported to.
+  #
+  # @param file [String] A filename.
+  # @returns [Boolean] +true+ if HowIs can export to the file, +false+
+  #   if it can't.
   def self.can_export_to?(file)
     # TODO: Check if the file is writable?
     supported_formats.include?(file.split('.').last)
   end
 
-  # Generate an analysis. Used internally for generate_report{,_file}.
+  # Generate an analysis.
+  # TODO: This may make more sense as Analysis.new().
   Contract C::KeywordArgs[repository: String,
-                          from: C::Optional[C::Or[String, nil]],
                           fetcher: C::Optional[Class],
                           analyzer: C::Optional[Class],
                           github: C::Optional[C::Any]] => C::Any
   def self.generate_analysis(repository:,
-        from: nil,
         fetcher: Fetcher.new,
         analyzer: Analyzer.new,
         github: nil)
-    if from
-      analysis = analyzer.from_file(from)
-    else
-      raw_data = fetcher.call(repository, github)
-      analysis = analyzer.call(raw_data)
-    end
+    raw_data = fetcher.call(repository, github)
+    analysis = analyzer.call(raw_data)
 
     analysis
   end
 
   # Generates YAML frontmatter, as is used in Jekyll and other blog engines.
@@ -99,9 +127,16 @@
     YAML.dump(frontmatter)
   end
 
   ##
   # Generates a series of report files based on a config Hash.
+  #
+  # @param config [Hash] A Hash specifying the formats, locations, etc
+  #   of the reports to generate.
+  # @param github (You don't need this.) An object to replace the GitHub
+  #   class when fetching data.
+  # @param report_class (You don't need this.) An object to replace the
+  #   HowIs::Report class when generating reports.
   def self.from_config(config,
         github: nil,
         report_class: nil)
     report_class ||= HowIs::Report
 