Spec description grammar [docs] (#4444)

mjago · Martin Verzilli · commit e2703175ebb6 · 2017-05-26T10:23:09.000-03:00
diff --git a/src/spec.cr b/src/spec.cr
@@ -1,8 +1,8 @@
 require "./spec/dsl"
 
-# Crystal's builtin testing library.
+# Crystal's built-in testing library.
 #
-# A basic spec looks like this:
+# A basic spec looks something like this:
 #
 # ```
 # require "spec"
@@ -24,25 +24,25 @@ require "./spec/dsl"
 #     end
 #   end
 #
-#   # lots of more specs
+#   # lots more specs
 #
 # end
 # ```
 #
-# With `describe` and a descriptive string test files are structured.
-# There commonly is one top level `describe` that defines which greater unit,
-# such as a class, is tested in this spec file. Further `describe` calls can
-# be nested within to specify smaller units under test like individual methods.
-# It can also be used to set up a certain context - think empty `Array` versus
-# `Array` with elements. There is also the `context` method that behaves just like
-# `describe` but has a lightly different meaning to the reader.
+# Test files are structured by use of the `describe` or `context` methods.
+# Typically a top level `describe` defines the `outer` unit (such as a class)
+# that is to be tested by the spec. Further `describe` calls can be nested within
+# the outer unit to specify smaller units under test (such as individual methods).
+# `describe` can also be used to set up a certain context - think empty `Array` versus
+# `Array` with elements. The `context` method behaves just like the `describe` method
+# and may be used instead, to emphasize context to the reader.
 #
-# Concrete test cases are defined with `it` within a `describe` block. A
-# descriptive string is supplied to `it` describing what that test case
+# Within a `describe` block, concrete test cases are defined with `it` . A
+# descriptive string is supplied to `it` describing what the test case
 # tests specifically.
 #
 # Specs then use the `should` method to verify that the expected value is
-# returned, see the example above for details.
+# returned. See the example above for details.
 #
 # By convention, specs live in the `spec` directory of a project. You can compile
 # and run the specs of a project by running:
@@ -51,14 +51,13 @@ require "./spec/dsl"
 # crystal spec
 # ```
 #
-# Also, you can compile and run individual spec files by providing their path:
+# You can also compile and run individual spec files by providing their path:
 #
 # ```shell
 # crystal spec spec/my/test/file_spec.cr
 # ```
 #
-# In addition, you can also run individual specs by optionally providing a line
-# number:
+# In addition, you may run individual specs by providing a line number:
 #
 # ```shell
 # crystal spec spec/my/test/file_spec.cr:14

Original file line number	Diff line number	Diff line change
`@@ -1,8 +1,8 @@`
`1`	`1`	`require "./spec/dsl"`
`2`	`2`
`3`		`-# Crystal's builtin testing library.`
	`3`	`+# Crystal's built-in testing library.`
`4`	`4`	`#`
`5`		`-# A basic spec looks like this:`
	`5`	`+# A basic spec looks something like this:`
`6`	`6`	`#`
`7`	`7`	# ```
`8`	`8`	`# require "spec"`
`@@ -24,25 +24,25 @@ require "./spec/dsl"`
`24`	`24`	`# end`
`25`	`25`	`# end`
`26`	`26`	`#`
`27`		`-# # lots of more specs`
	`27`	`+# # lots more specs`
`28`	`28`	`#`
`29`	`29`	`# end`
`30`	`30`	# ```
`31`	`31`	`#`
`32`		-# With `describe` and a descriptive string test files are structured.
`33`		-# There commonly is one top level `describe` that defines which greater unit,
`34`		-# such as a class, is tested in this spec file. Further `describe` calls can
`35`		`-# be nested within to specify smaller units under test like individual methods.`
`36`		-# It can also be used to set up a certain context - think empty `Array` versus
`37`		-# `Array` with elements. There is also the `context` method that behaves just like
`38`		-# `describe` but has a lightly different meaning to the reader.
	`32`	+# Test files are structured by use of the `describe` or `context` methods.
	`33`	+# Typically a top level `describe` defines the `outer` unit (such as a class)
	`34`	+# that is to be tested by the spec. Further `describe` calls can be nested within
	`35`	`+# the outer unit to specify smaller units under test (such as individual methods).`
	`36`	+# `describe` can also be used to set up a certain context - think empty `Array` versus
	`37`	+# `Array` with elements. The `context` method behaves just like the `describe` method
	`38`	`+# and may be used instead, to emphasize context to the reader.`
`39`	`39`	`#`
`40`		-# Concrete test cases are defined with `it` within a `describe` block. A
`41`		-# descriptive string is supplied to `it` describing what that test case
	`40`	+# Within a `describe` block, concrete test cases are defined with `it` . A
	`41`	+# descriptive string is supplied to `it` describing what the test case
`42`	`42`	`# tests specifically.`
`43`	`43`	`#`
`44`	`44`	# Specs then use the `should` method to verify that the expected value is
`45`		`-# returned, see the example above for details.`
	`45`	`+# returned. See the example above for details.`
`46`	`46`	`#`
`47`	`47`	# By convention, specs live in the `spec` directory of a project. You can compile
`48`	`48`	`# and run the specs of a project by running:`
`@@ -51,14 +51,13 @@ require "./spec/dsl"`
`51`	`51`	`# crystal spec`
`52`	`52`	# ```
`53`	`53`	`#`
`54`		`-# Also, you can compile and run individual spec files by providing their path:`
	`54`	`+# You can also compile and run individual spec files by providing their path:`
`55`	`55`	`#`
`56`	`56`	# ```shell
`57`	`57`	`# crystal spec spec/my/test/file_spec.cr`
`58`	`58`	# ```
`59`	`59`	`#`
`60`		`-# In addition, you can also run individual specs by optionally providing a line`
`61`		`-# number:`
	`60`	`+# In addition, you may run individual specs by providing a line number:`
`62`	`61`	`#`
`63`	`62`	# ```shell
`64`	`63`	`# crystal spec spec/my/test/file_spec.cr:14`