Add Yard configuration and correct Yard syntax.

.gitignore

@@ -75,3 +75,10 @@ Gemfile.lock
 
 src/testup/ui/js/*.*
 src/testup/ui/images/*
+
+############
+## Yard
+############
+
+.yardoc/
+doc/

.yardopts

@@ -0,0 +1,7 @@
+--title "TestUp 2 for SketchUp - A GUI wrapper for running Minitest in SketchUp"
+--no-private
+--markup markdown
+src/**/*.rb
+-
+README.md
+LICENSE

src/testup/api.rb

@@ -1,6 +1,6 @@
 #-------------------------------------------------------------------------------
 #
-# Copyright 2013-2018 Trimble Inc.
+# Copyright 2013-2024 Trimble Inc.
 # License: The MIT License (MIT)
 #
 #-------------------------------------------------------------------------------
@@ -27,6 +27,10 @@ module API
     #
     # @param [TestUp::Report::TestSuite, Pathname, String] test_suite
     # @param [Hash] config
+    # @option config [String] 'Seed' Integer numeric for the Minitest random seed.
+    # @option config [String] 'Verbose' Turns on verbose reporting if key is present.
+    # @option config [String] 'Output' JSON file to output results to.
+    # @option config [Array] 'Tests'
     def self.run_suite_without_gui(test_suite, config = {})
       test_suite_path = if test_suite.is_a?(TestUp::Report::TestSuite)
                           Pathname.new(test_suite.path)
@@ -70,22 +74,33 @@ def self.run_suite_without_gui(test_suite, config = {})
     end
 
     # @example Run a test case:
-    #   TestUp.run_tests(["TC_Sketchup_Edge#"])
+    #   TestUp::API.run_tests(["TC_Sketchup_Edge#"], path: path)
     #
     # @example Run single test:
-    #   TestUp.run_tests(["TC_Sketchup_Edge#start"])
+    #   TestUp::API.run_tests(["TC_Sketchup_Edge#start"], path: path)
     #
     # @example Run a set of test cases and/or tests:
     #   tests = [
     #     "TC_Sketchup_Face#",
     #     "TC_Sketchup_Edge#start", "TC_Sketchup_Edge#end"
     #   ]
-    #   TestUp.run_tests(tests)
+    #   path = "path/to/testsuite/"
+    #   TestUp::API.run_tests(tests, path: path)
+    #
+    # @todo The `path` parameter is not optional.
+    # @todo The `title` parameter should be extracted from the path.
     #
     # @param [Array<String>] tests list of tests or test cases to run.
     # @param [String] title Name of test_suite
     # @param [String] path Path to the test_suite
     # @param [Hash] options
+    # @option options [Boolean] :show_console Open the Ruby Console before running tests.
+    # @option options [Boolean] :clear_console Clear the Ruby Console before running tests.
+    # @option options [Boolean] :ci Generate JSON report to STDOUT.
+    # @option options [String] :ci_out Pipe JSON report to file.
+    # @option options [Boolean] :ui Update the TestUp dialog.
+    # @option options [Integer] :seed Set the randomization seed for Minitest.
+    # @option options [Boolean] :verbose
     # @yield [Report::TestSuite]
     # @return [Boolean]
     def self.run_tests(tests, title: 'Untitled', path: nil, options: {})
@@ -129,7 +144,7 @@ def self.run_test_suite(test_suite, options: {})
     # @param [String] title
     # @param [String] path
     # @param [Array<Hash>] results
-    # @result [Report::TestSuite]
+    # @return [Report::TestSuite]
     def self.test_suite_from_results(title, path, results)
       tests = {}
       results.each { |result|

src/testup/command.rb

@@ -3,7 +3,7 @@ module TestUp
 # return a UI::Command object. So instead this module is used that will extend
 # the instance created with it's #create method.
 #
-# @example
+# @example Creating a Command object:
 #   cmd = Command.create('Hello World') {
 #     Extension.hello_world
 #   }

src/testup/core.rb

@@ -83,7 +83,7 @@ def self.toggle_verbose_console_tests
   end
 
   # TODO(thomthom): Move this method. Maybe to the Reporter class if the
-  # @num_tests_being_run instance variable also can be moved there.
+  # `@num_tests_being_run`` instance variable also can be moved there.
   def self.update_testing_progress(num_tests_run)
     progress = TaskbarProgress.new
     progress.set_value(num_tests_run, @num_tests_being_run)

src/testup/coverage.rb

@@ -11,7 +11,7 @@ module TestUp
 # TODO: Rename to CoverageDiscoverer
 class Coverage
 
-  # @param [String] settings_id
+  # @param [String] testsuite_path
   def initialize(testsuite_path)
     unless File.directory?(testsuite_path)
       raise ArgumentError, "Not a valid directory: #{testsuite_path}"

src/testup/coverage_discoverer.rb

@@ -25,7 +25,7 @@ def report(discovered_suite)
 
     private
 
-    # @param [Array<Report::TestCase>] expected
+    # @param [Array<Report::TestCase>] expected_test_case
     # @param [Array<Report::TestCase>] missing
     # @return [Float]
     def compute_percentage(expected_test_case, missing)

src/testup/log.rb

@@ -31,7 +31,7 @@ def self.set_tracing(category, enabled)
     end
 
     # @param [Symbol] category
-    # @param [Boolean]
+    # @return [Boolean]
     def self.tracing(category)
       @trace[category] || false
     end

src/testup/manifest.rb

@@ -13,7 +13,7 @@ class Manifest
 
     attr_reader :filename
 
-    # @param [String] filename
+    # @param [String] manifest_filename
     def initialize(manifest_filename)
       @filename = manifest_filename
       @expected = parse_manifest(manifest_filename)

src/testup/minitest_plugins/minitest/testup_plugin.rb

@@ -30,9 +30,10 @@ def self.plugin_testup_options opts, options # :nodoc:
     end
   end
 
+  # @param [Hash] options Options provided by {.plugin_testup_options}
   def self.plugin_testup_init(options)
     TestUp::Log.trace :minitest, 'Minitest TestUp Extension loading...'
-    if TestUp.settings[:run_in_gui]
+    if options[:testup_gui]
       TestUp::Log.trace :minitest, 'Minitest TestUp Extension in GUI mode'
       # Disable the default reporters as otherwise they'll print lots of data to
       # the console while the test runs. No need for that.

src/testup/report/collection.rb

@@ -17,7 +17,7 @@ module TestUp
   module Report
     class Collection < SortedSet
 
-      # @param [Integer, #hash]
+      # @param [Integer, #hash] value
       def [](value)
         # return @hash.keys[value] if value.is_a?(Integer)
         return each.to_a[value] if value.is_a?(Integer)

src/testup/report/test.rb

@@ -47,7 +47,7 @@ def hash
         @id.hash
       end
 
-      # @param [Report::Test]
+      # @param [Report::Test] test
       # @return [Boolean]
       def merge_result(test)
         return false if test.result.nil?

src/testup/report/test_coverage.rb

@@ -27,7 +27,7 @@ def self.from_hash(hash)
       end
 
       # @param [Float] percent
-      # @param [Hash, Array<Report::TestCase>]
+      # @param [Hash, Array<Report::TestCase>] missing
       def initialize(percent, missing)
         @percent = percent.to_f
         @missing = restructure(missing)

src/testup/report/test_suite.rb

@@ -93,14 +93,14 @@ def rediscover(other_test_suite)
         self
       end
 
-      # @param [Report::TestCase, Symbol, String]
+      # @param [Report::TestCase, Symbol, String] test_case
       # @return [Report::TestCase]
       def test_case(test_case)
         @test_cases[test_case]
       end
       alias_method :[], :test_case
 
-      # @param [Report::TestCase, String]
+      # @param [Report::TestCase, String] test_case
       def test_case?(test_case)
         !test_case(test_case).nil?
       end

src/testup/sketchup_test_utilities.rb

@@ -334,7 +334,7 @@ def assert_no_notification
       end
 
       # @param [String] event
-      # @param [Integer] argument
+      # @param [Integer] argument_index
       # @param [Class] type
       # @param [Object] expected
       def assert_callback_data(event, argument_index, type, expected)

src/testup/test_discoverer.rb

@@ -116,7 +116,7 @@ def discover_testcases(testsuite_path)
       }
     end
 
-    # @param [Array<String>] testsuite_paths
+    # @param [Array<String>] testsuite_path
     # @return [Array<String>] Path to all test case files found.
     def discover_testcase_source_files(testsuite_path)
       # Log.debug ">>> #{self.class}.discover_testcase_source_files(...)"

src/testup/test_runner.rb

@@ -25,6 +25,11 @@ def initialize(title: 'Untitled', path: nil)
 
     # @param [Array<String>] tests
     # @param [Hash] options
+    # @option options [Boolean] :ci Generate JSON report to STDOUT.
+    # @option options [String] :ci_out Pipe JSON report to file.
+    # @option options [Boolean] :ui Update the TestUp dialog.
+    # @option options [Integer] :seed Set the randomization seed for Minitest.
+    # @option options [Boolean] :verbose
     # @yield [Array<Report::TestSuite>]
     # return [Boolean]
     def run(tests, options = {})
@@ -40,6 +45,11 @@ def run(tests, options = {})
 
     # @param [Array<String>] tests
     # @param [Hash] options
+    # @option options [Boolean] :ci Generate JSON report to STDOUT.
+    # @option options [String] :ci_out Pipe JSON report to file.
+    # @option options [Boolean] :ui Update the TestUp dialog.
+    # @option options [Integer] :seed Set the randomization seed for Minitest.
+    # @option options [Boolean] :verbose
     # return [nil]
     def run_tests(tests, options)
       TestUp::FileReporter.set_run_info(@title, @path) # Hack!
@@ -64,6 +74,11 @@ def run_tests(tests, options)
 
     # @param [Array<String>] tests
     # @param [Hash] options
+    # @option options [Boolean] :ci Generate JSON report to STDOUT.
+    # @option options [String] :ci_out Pipe JSON report to file.
+    # @option options [Boolean] :ui Update the TestUp dialog.
+    # @option options [Integer] :seed Set the randomization seed for Minitest.
+    # @option options [Boolean] :verbose
     # return [Array<String>]
     def minitest_arguments(tests, options)
       arguments = []

src/testup/ui/runner.rb

@@ -116,7 +116,9 @@ def event_window_ready
     # @param [Hash] test_suite_json JSON data from JavaScript side.
     def event_run_tests(test_suite_json)
       Log.trace :callback, 'event_run_tests(...)'
-      options = {}
+      options = {
+        ui: TestUp.settings[:run_in_gui],
+      }
       test_suite = Report::TestSuite.from_hash(test_suite_json)
       TestUp::API.run_test_suite(test_suite, options: options) { |results|
         test_suite.merge_results(results)
@@ -131,7 +133,8 @@ def event_rerun_tests
       return unless run_file
       run_config = TestUp::Runs.read_config(run_file)
       options = {
-        seed: run_config[:seed]
+        seed: run_config[:seed],
+        ui: TestUp.settings[:run_in_gui],
       }
       tests = run_config[:tests]
       title = run_config[:test_suite]
@@ -225,7 +228,7 @@ def discover_tests
       nil
     end
 
-    # @param [Report::TestSuite] test_suite
+    # @param [Report::TestSuite] test_suites
     # @return [nil]
     def rediscover_tests(test_suites)
       Log.trace :discover, "rediscover_tests(...)"