Change "what" to "description"

src/spectator.cr

@@ -24,7 +24,7 @@ module Spectator
   # NOTE: Inside the block, the `Spectator` prefix is no longer needed.
   # Actually, prefixing methods and macros with `Spectator`
   # most likely won't work and can cause compiler errors.
-  macro describe(what, &block)
+  macro describe(description, &block)
     # This macro creates the foundation for all specs.
     # Every group of examples is defined a separate module - `SpectatorExamples`.
     # There's multiple reasons for this.
@@ -39,15 +39,15 @@ module Spectator
 
     # Root-level class that contains all examples and example groups.
     class SpectatorTest
-      # Pass off the "what" argument and block to `DSL::StructureDSL.describe`.
+      # Pass off the description argument and block to `DSL::StructureDSL.describe`.
       # That method will handle creating a new group for this spec.
-      describe({{what}}) {{block}}
+      describe({{description}}) {{block}}
     end
   end
 
   # ditto
-  macro context(what, &block)
+  macro context(description, &block)
-    describe({{what}}) {{block}}
+    describe({{description}}) {{block}}
   end
 
   # Flag indicating whether Spectator should automatically run tests.

src/spectator/dsl/examples.cr

@@ -3,14 +3,14 @@ require "../spec_builder"
 
 module Spectator
   module DSL
-    macro it(what, _source_file = __FILE__, _source_line = __LINE__, &block)
+    macro it(description, _source_file = __FILE__, _source_line = __LINE__, &block)
       {% if block.is_a?(Nop) %}
-        {% if what.is_a?(Call) %}
+        {% if description.is_a?(Call) %}
           def %run
-            {{what}}
+            {{description}}
           end
         {% else %}
-          {% raise "Unrecognized syntax: `it #{what}` at #{_source_file}:#{_source_line}" %}
+          {% raise "Unrecognized syntax: `it #{description}` at #{_source_file}:#{_source_line}" %}
         {% end %}
       {% else %}
         def %run
@@ -20,7 +20,7 @@ module Spectator
 
       %source = ::Spectator::Source.new({{_source_file}}, {{_source_line}})
       ::Spectator::SpecBuilder.add_example(
-        {{what.is_a?(StringLiteral) ? what : what.stringify}},
+        {{description.is_a?(StringLiteral) ? description : description.stringify}},
         %source,
         {{@type.name}}
       ) { |test| test.as({{@type.name}}).%run }

src/spectator/dsl/groups.cr

@@ -2,26 +2,26 @@ require "../spec_builder"
 
 module Spectator
   module DSL
-    macro context(what, _source_file = __FILE__, _source_line = __LINE__, &block)
+    macro context(description, _source_file = __FILE__, _source_line = __LINE__, &block)
       class Context%context < {{@type.id}}
         {%
-          description = if what.is_a?(StringLiteral)
+          description = if description.is_a?(StringLiteral)
-                          if what.starts_with?("#") || what.starts_with?(".")
+                          if description.starts_with?("#") || description.starts_with?(".")
-                            what.id.symbolize
+                            description.id.symbolize
                           else
-                            what
+                            description
                           end
                         else
-                          what.symbolize
+                          description.symbolize
                         end
         %}
 
         %source = ::Spectator::Source.new({{_source_file}}, {{_source_line}})
         ::Spectator::SpecBuilder.start_group({{description}}, %source)
 
-        {% if what.is_a?(Path) || what.is_a?(Generic) %}
+        {% if description.is_a?(Path) || description.is_a?(Generic) %}
           macro described_class
-            {{what}}
+            {{description}}
           end
 
           def subject(*args)
@@ -35,8 +35,8 @@ module Spectator
       end
     end
 
-    macro describe(what, &block)
+    macro describe(description, &block)
-      context({{what}}) {{block}}
+      context({{description}}) {{block}}
     end
 
     macro sample(collection, count = nil, _source_file = __FILE__, _source_line = __LINE__, &block)

src/spectator/example.cr

@@ -23,7 +23,7 @@ module Spectator
       @test_wrapper.source
     end
 
-    def what : String | Symbol
+    def description : String | Symbol
       @test_wrapper.description
     end
 
@@ -66,7 +66,7 @@ module Spectator
     def to_s(io)
       @group.to_s(io)
       io << ' ' unless symbolic? && @group.symbolic?
-      io << what
+      io << description
     end
 
     # Creates the JSON representation of the example,

src/spectator/example_component.cr

@@ -3,8 +3,11 @@ module Spectator
   # This is used as the base node type for the composite design pattern.
   abstract class ExampleComponent
     # Text that describes the context or test.
-    # TODO: Rename to description.
+    abstract def description : Symbol | String
-    abstract def what : Symbol | String
+
+    def full_description
+      to_s
+    end
 
     abstract def source : Source
 

src/spectator/formatting/document_formatter.cr

@@ -28,7 +28,7 @@ module Spectator::Formatting
     # Produces a single character output based on a result.
     def end_example(result)
       @previous_hierarchy.size.times { @io.print INDENT }
-      @io.puts result.call(Color) { result.example.what }
+      @io.puts result.call(Color) { result.example.description }
     end
 
     # Produces a list of groups making up the hierarchy for an example.
@@ -56,7 +56,7 @@ module Spectator::Formatting
     private def print_sub_hierarchy(index, sub_hierarchy)
       sub_hierarchy.each do |group|
         index.times { @io.print INDENT }
-        @io.puts group.what
+        @io.puts group.description
         index += 1
       end
     end

src/spectator/nested_example_group.cr

@@ -6,7 +6,7 @@ module Spectator
   class NestedExampleGroup < ExampleGroup
     # Description from the user of the group's contents.
     # This is a symbol when referencing a type.
-    getter what : Symbol | String
+    getter description : Symbol | String
 
     getter source : Source
 
@@ -14,23 +14,23 @@ module Spectator
     getter parent : ExampleGroup
 
     # Creates a new example group.
-    # The *what* argument is a description from the user.
+    # The *description* argument is a description from the user.
     # The *parent* should contain this group.
     # After creating this group, the parent's children should be updated.
     # The parent's children must contain this group,
     # otherwise there may be unexpected behavior.
     # The *hooks* are stored to be triggered later.
-    def initialize(@what, @source, @parent, context)
+    def initialize(@description, @source, @parent, context)
       super(context)
     end
 
     # Indicates wheter the group references a type.
     def symbolic? : Bool
-      @what.is_a?(Symbol)
+      @description.is_a?(Symbol)
     end
 
     # Creates a string representation of the group.
-    # The string consists of `#what` appended to the parent.
+    # The string consists of `#description` appended to the parent.
     # This results in a string like:
     # ```text
     # Foo#bar does something
@@ -48,7 +48,7 @@ module Spectator
     def to_s(io)
       parent.to_s(io)
       io << ' ' unless (symbolic? || parent.is_a?(RootExampleGroup)) && parent.symbolic?
-      io << what
+      io << description
     end
   end
 end

src/spectator/root_example_group.cr

@@ -5,8 +5,8 @@ module Spectator
   # The root has no parent.
   class RootExampleGroup < ExampleGroup
     # Dummy value - this should never be used.
-    def what : Symbol | String
+    def description : Symbol | String
-      "ROOT"
+      :root
     end
 
     def source : Source

src/spectator/spec_builder/nested_example_group_builder.cr

@@ -3,12 +3,12 @@ require "./example_group_builder"
 
 module Spectator::SpecBuilder
   class NestedExampleGroupBuilder < ExampleGroupBuilder
-    def initialize(@what : String | Symbol, @source : Source)
+    def initialize(@description : String | Symbol, @source : Source)
     end
 
     def build(parent_group)
       context = TestContext.new(parent_group.context, build_hooks, parent_group.context.values)
-      NestedExampleGroup.new(@what, @source, parent_group, context).tap do |group|
+      NestedExampleGroup.new(@description, @source, parent_group, context).tap do |group|
         group.children = children.map do |child|
           child.build(group).as(ExampleComponent)
         end

src/spectator/spec_builder/sample_example_group_builder.cr

@@ -2,15 +2,15 @@ require "./nested_example_group_builder"
 
 module Spectator::SpecBuilder
   class SampleExampleGroupBuilder(T) < NestedExampleGroupBuilder
-    def initialize(what : String | Symbol, source : Source, @id : Symbol, @label : String, @collection_builder : TestValues -> Array(T))
+    def initialize(description : String | Symbol, source : Source, @id : Symbol, @label : String, @collection_builder : TestValues -> Array(T))
-      super(what, source)
+      super(description, source)
     end
 
     def build(parent_group)
       values = parent_group.context.values
       collection = @collection_builder.call(values)
       context = TestContext.new(parent_group.context, build_hooks, values)
-      NestedExampleGroup.new(@what, @source, parent_group, context).tap do |group|
+      NestedExampleGroup.new(@description, @source, parent_group, context).tap do |group|
         group.children = collection.map do |element|
           build_sub_group(group, element).as(ExampleComponent)
         end
@@ -18,7 +18,7 @@ module Spectator::SpecBuilder
     end
 
     private def build_sub_group(parent_group, element)
-      values = parent_group.context.values.add(@id, @what.to_s, element)
+      values = parent_group.context.values.add(@id, @description.to_s, element)
       context = TestContext.new(parent_group.context, ExampleHooks.empty, values)
       NestedExampleGroup.new("#{@label} = #{element.inspect}", @source, parent_group, context).tap do |group|
         group.children = children.map do |child|