From 20680f37cb1d8d50f3b580fe1168f5d7f9513d35 Mon Sep 17 00:00:00 2001 From: Michael Miller Date: Sat, 30 Jan 2021 15:39:29 -0700 Subject: [PATCH] Add docs --- src/spectator/dsl/examples.cr | 9 +++++++++ src/spectator/dsl/groups.cr | 16 ++++++++++++++++ 2 files changed, 25 insertions(+) diff --git a/src/spectator/dsl/examples.cr b/src/spectator/dsl/examples.cr index a309901..b466b02 100644 --- a/src/spectator/dsl/examples.cr +++ b/src/spectator/dsl/examples.cr @@ -10,6 +10,11 @@ module Spectator::DSL # Defines a macro to generate code for an example. # The *name* is the name given to the macro. + # + # Default tags can be provided with *tags* and *metadata*. + # The tags are merged with parent groups. + # Any items with falsey values from *metadata* remove the corresponding tag. + # # TODO: Mark example as pending if block is omitted. macro define_example(name, *tags, **metadata) # Defines an example. @@ -24,6 +29,10 @@ module Spectator::DSL # # The example will be marked as pending if the block is omitted. # A block or name must be provided. + # + # Tags can be specified by adding symbols (keywords) after the first argument. + # Key-value pairs can also be specified. + # Any falsey items will remove a previously defined tag. macro {{name.id}}(what = nil, *tags, **metadata, &block) \{% raise "Cannot use '{{name.id}}' inside of a test block" if @def %} \{% raise "A description or block must be provided. Cannot use '{{name.id}}' alone." unless what || block %} diff --git a/src/spectator/dsl/groups.cr b/src/spectator/dsl/groups.cr index 20f8a4e..0bb8bfd 100644 --- a/src/spectator/dsl/groups.cr +++ b/src/spectator/dsl/groups.cr @@ -8,10 +8,26 @@ module Spectator::DSL module Groups include Tags + # Defines a macro to generate code for an example group. + # The *name* is the name given to the macro. + # + # Default tags can be provided with *tags* and *metadata*. + # The tags are merged with parent groups. + # Any items with falsey values from *metadata* remove the corresponding tag. macro define_example_group(name, *tags, **metadata) # Defines a new example group. # The *what* argument is a name or description of the group. # + # The first argument names the example (test). + # Typically, this specifies what is being tested. + # This argument is also used as the subject. + # When it is a type name, it becomes an explicit, which overrides any previous subjects. + # Otherwise it becomes an implicit subject, which doesn't override explicitly defined subjects. + # + # Tags can be specified by adding symbols (keywords) after the first argument. + # Key-value pairs can also be specified. + # Any falsey items will remove a previously defined tag. + # # TODO: Handle string interpolation in example and group names. macro {{name.id}}(what, *tags, **metadata, &block) \{% raise "Cannot use '{{name.id}}' inside of a test block" if @def %}