docs: review inline options (#24)

Highlights:
- Move `:apply` after all other opts, as it applies to all other opts.
- Describe long and short forms of `:skip`

Author: lread

doc/example.adoc

@@ -102,31 +102,35 @@ It is sometimes just nice to know that your code snippet will run without except
 == Inline Options
 You can, to some limited extent, communicate your intent to test-doc-blocks.
 
-Test-doc-blocks will look for AsciiDoc comments that begin with `:test-doc-blocks`.
+Test-doc-blocks will look for AsciiDoc `:test-doc-blocks` comment lines.
 
 It currently understands the following options:
 
-* `:test-doc-blocks/apply` - controls to what code blocks options are applied
 * `:test-doc-blocks/skip` - skips the next code block
 * `:test-doc-blocks/reader-cond` - wraps your code block in a reader conditional
 * `:test-doc-blocks/test-ns` - specifies the output test namespace
 * `:test-doc-blocks/platform` - specifies Clojure file type to generate for test ns
 * `:test-doc-blocks/meta` - attach metadata to generated tests
+* `:test-doc-blocks/apply` - controls to what code blocks options are applied
 
-=== Applying Options - :apply
-
-By default, test-doc-blocks will create tests for all Clojure code blocks it finds in the files you specified.
+=== Skipping Code Blocks - :skip
 
-You can change this by including the `:test-doc-blocks/apply` option:
+By default, test-doc-blocks will create tests for all Clojure code blocks it finds.
 
-* `:next` - default - applies new options to next Clojure code block only
-* `:all-next` - applies new options to all subsequent code blocks in the document until specifically overridden with new opts
+Tell test-doc-blocks to skip the next Clojure code block via `//#:test-doc-blocks {:skip true}`:
 
-=== Skipping Code Blocks - :skip
+[source,asciidoc]
+....
+//#:test-doc-blocks {:skip true}
+[source,clojure]
+----
+;; no tests will be generated for this code Clojure code block
 
-By default, test-doc-blocks will create tests for all Clojure code blocks it finds.
+(something we don't want to test...
+----
+....
 
-Tell test-doc-blocks to skip the next Clojure code block via the following AsciiDoc comment:
+Because `:skip` is a boolean, you can use the shorter `//:test-doc-blocks/skip`:
 
 [source,asciidoc]
 ....
@@ -135,7 +139,7 @@ Tell test-doc-blocks to skip the next Clojure code block via the following Ascii
 ----
 ;; no tests will be generated for this code Clojure code block
 
-(something we don't want to test)
+(something we don't want to test...
 ----
 ....
 
@@ -188,7 +192,8 @@ Test-doc-blocks does no special checking, but `:reader-cond` only makes sense fo
 === Specifying Test Namespace - :test-ns
 
 By default, test-doc-blocks will generate tests to namespaces based on document filenames.
-This file is named `example.adoc`. Test-doc-blocks, up to this point, has been generating tests to the `example-adoc-test` namespace.
+This file you are reading now is named `example.adoc`.
+Test-doc-blocks, up to this point, has been generating tests to the `example-adoc-test` namespace.
 
 If this does not work for you, you can override this default via an AsciiDoc comment:
 
@@ -238,7 +243,7 @@ When specifying the platform, remember that:
 * For Clojure `my-ns-file.clj` will be picked over `my-ns-file.cljc`
 * For ClojureScript `my-ns-file.cljs` will be picked over `my-ns-file.cljc`
 
-So if you are generating mixed platforms, you might want to specify the test-ns as well.
+So if you are generating mixed platforms, you might want to specify the test-ns as well:
 
 [source,asciidoc]
 ....
@@ -301,6 +306,62 @@ user=> (into [] {:a 1})
 ----
 ....
 
+=== Applying Options - :apply
+
+Use the `:test-doc-blocks/apply` option to control which code blocks your specified option(s) apply to:
+
+* `:next` - default - applies new options to next Clojure code block only
+* `:all-next` - applies new options to all subsequent code blocks in the document until specifically overridden with new opts
+
+For example, maybe you want test-doc-blocks to skip code blocks by default:
+
+[source,asciidoc]
+....
+//#:test-doc-blocks{:skip true :apply :all-next}
+....
+
+All subsequent code blocks would be skipped.
+
+[source,asciidoc]
+....
+[source,clojure]
+----
+;; I am a code block that is skipped by test-doc-blocks
+(maybe some code that won't compile ...
+----
+....
+
+Then you could choose to not skip a code block like so:
+[source,asciidoc]
+....
+//#:test-doc-blocks{:skip false}
+[source,clojure]
+----
+;; A test will be generated for this code block
+(apply str (interpose " " ["don't" "skip" "me!"]))
+;; =>  "don't skip me!"
+----
+....
+
+To have test-doc-blocks stop skipping code blocks by default:
+
+[source,asciidoc]
+....
+//#:test-doc-blocks{:skip false :apply :all-next}
+....
+
+And now test-doc-blocks will generate tests for subsequent code blocks.
+
+[source,asciidoc]
+....
+[source,clojure]
+----
+;; A test will be generated for this code block
+(apply str (interpose " " ["test" "me" "by" "default"]))
+;; =>  "test me by default"
+----
+....
+
 // Notice the use of CommonMark syntax for section title here, we test that we recognize this syntax
 ## Section Titles
 Test-doc-blocks will try to give each test block some context by including its filename, section title and starting line number.
@@ -324,7 +385,7 @@ And this level 2 type
 ---------------------
 ----
 
-This code block should include "Section Titles" as part of the context for its generated test.
+This code block should include "Section Titles" (the actual title of this section) as part of the context for its generated test.
 
 [source,markdown]
 ....

doc/example.md

@@ -91,38 +91,40 @@ It is sometimes just nice to know that your code snippet will run without except
 ## Inline Options
 You can, to some limited extent, communicate your intent to test-doc-blocks.
 
-Test-doc-blocks will look for CommonMark comments that begin with `:test-doc-blocks`.
+Test-doc-blocks will look for CommonMark `:test-doc-blocks` comment lines.
 
 It currently understands the following options:
 
-- `:test-doc-blocks/apply` - controls to what code blocks options are applied
 - `:test-doc-blocks/skip` - skips the next code block
 - `:test-doc-blocks/reader-cond` - wraps your code block in a reader conditional
 - `:test-doc-blocks/test-ns` - specifies the output test namespace
 - `:test-doc-blocks/platform` - specifies Clojure file type to generate for test ns
 - `:test-doc-blocks/meta` - attach metadata to generated tests
+- `:test-doc-blocks/apply` - controls to what code blocks options are applied
 
-### Applying Options - :apply
-
-By default, new options are applied to the next Clojure code block only.
+### Skipping Code Blocks - :skip
 
-You can change this by including the `:test-doc-blocks/apply` option:
+By default, test-doc-blocks will create tests for all Clojure code blocks it finds in the files you specified.
 
-- `:next` - default - applies new options to next Clojure code block only
-- `:all-next` - applies new options to all subsequent code blocks in the document until specifically overridden with new opts
+Tell test-doc-blocks to skip the next Clojure code block via `<!-- #:test-doc-blocks {:skip true} -->`:
 
-### Skipping Code Blocks - :skip
+~~~markdown
+<!-- #:test-doc-blocks {:skip true} -->
+```Clojure
+;; no tests will be generated for this Clojure code block
 
-By default, test-doc-blocks will create tests for all Clojure code blocks it finds in the files you specified.
+(something we don't want to test ...
+```
+~~~
 
-Tell test-doc-blocks to skip the next Clojure code block via the following CommonMark comment:
+Because `:skip` is a boolean, you can use the shorter `<!-- :test-doc-blocks/skip -->`:
 
 ~~~markdown
 <!-- :test-doc-blocks/skip -->
 ```Clojure
 ;; no tests will be generated for this Clojure code block
 
-(something we don't want to test)
+(something we don't want to test ...
 ```
 ~~~
 
@@ -169,7 +171,7 @@ Test-doc-blocks does no special checking, but `:reader-cond` only makes sense fo
 ### Specifying Test Namespace - :test-ns
 
 By default, test-doc-blocks will generate tests to namespaces based on document filenames.
-This file is named `example.md`. Test-doc-blocks, up to this point has been generating tests to the `example-md-test` namespace.
+This file your are reading now is named `example.md`. Test-doc-blocks, up to this point has been generating tests to the `example-md-test` namespace.
 
 If this does not work for you, you can override this default via a CommonMark comment:
 
@@ -217,7 +219,7 @@ When specifying the platform, remember that:
 - For Clojure `my-ns-file.clj` will be picked over `my-ns-file.cljc`
 - For ClojureScript `my-ns-file.cljs` will be picked over `my-ns-file.cljc`
 
-So if you are generating mixed platforms, you might want to specify the test-ns as well.
+So if you are generating mixed platforms, you might want to specify the test-ns as well:
 
 ~~~markdown
 <!-- #:test-doc-blocks{:platform :cljs :test-ns example-md-cljs-test} -->
@@ -274,11 +276,60 @@ user=> (into [] {:a 1})
 ```
 ~~~
 
+### Applying Options - :apply
+
+Use the `:test-doc-blocks/apply` option to control which code blocks your specified option(s) apply to:
+
+- `:next` - default - applies new options to next Clojure code block only
+- `:all-next` - applies new options to all subsequent code blocks in the document until specifically overridden with new opts
+
+For example, maybe you want test-doc-blocks to skip code blocks by default:
+
+~~~markdown
+<!-- #:test-doc-blocks{:skip true :apply :all-next} -->
+~~~
+
+All subsequent code blocks would be skipped.
+
+~~~markdown
+```clojure
+;; I am a code block that is skipped by test-doc-blocks
+(maybe some code that won't compile ...
+```
+~~~
+
+Then you could choose to not skip a code block like so:
+
+~~~markdown
+<!-- #:test-doc-blocks{:skip false} -->
+```clojure
+;; A test will be generated for this code block
+(apply str (interpose " " ["don't" "skip" "me!"]))
+;; =>  "don't skip me!"
+```
+~~~
+
+To have test-doc-blocks stop skipping code blocks by default:
+
+~~~markdown
+<!-- #:test-doc-blocks{:skip false :apply :all-next} -->
+~~~
+
+And now test-doc-blocks will generate tests for subsequent code blocks.
+
+~~~markdown
+```clojure
+;; A test will be generated for this code block
+(apply str (interpose " " ["test" "me" "by" "default"]))
+;; =>  "test me by default"
+```
+~~~
+
 # Section Titles
 
 Test-doc-blocks will try to give each test block some context by including its filename, section title and starting line number.
 
-This code block should include "Section Titles" as part of the context for its generated test.
+This code block should include "Section Titles" (the actual title of this section) as part of the context for its generated test.
 
 ~~~markdown
 ```Clojure

test-resources/expected/test-doc-blocks/test/example_adoc_cljs_test.cljs

@@ -6,7 +6,7 @@
   (:import goog.events.EventType))
 
 (clojure.test/deftest block-0001
-  (clojure.test/testing  "doc/example.adoc - line 247 - Specifying The Platform - :platform"
+  (clojure.test/testing  "doc/example.adoc - line 252 - Specifying The Platform - :platform"
 ;; this code block will generate a test under example-adoc-cljs-test ns to a .cljs file
 
 nil

test-resources/expected/test-doc-blocks/test/example_adoc_inline_ns_test.cljc

@@ -10,7 +10,7 @@
   (:import #?@(:clj [java.util.List java.util.Queue java.util.Set] :cljs [goog.math.Long goog.math.Vec2 goog.math.Vec3])))
 
 (clojure.test/deftest block-0001
-  (clojure.test/testing  "doc/example.adoc - line 411 - Inline requires and imports"
+  (clojure.test/testing  "doc/example.adoc - line 472 - Inline requires and imports"
 ;; Stick the basics for requires, shorthand notation isn't supported
 
 ;; Some examples:

test-resources/expected/test-doc-blocks/test/example_adoc_inline_refer_clojure_test.cljc

@@ -7,7 +7,7 @@
             [clojure.edn :refer [read-string]]))
 
 (clojure.test/deftest block-0001
-  (clojure.test/testing  "doc/example.adoc - line 442 - Inline refer-clojure"
+  (clojure.test/testing  "doc/example.adoc - line 503 - Inline refer-clojure"
 ;; a contrived example that uses uses clojure.edn/read-string in place
 ;; of clojure.core/read-string and excludes clojure.core/for
 nil

test-resources/expected/test-doc-blocks/test/example_adoc_new_ns/ns1_test.cljc

@@ -6,7 +6,7 @@
             [clojure.string :as string]))
 
 (clojure.test/deftest block-0001
-  (clojure.test/testing  "doc/example.adoc - line 215 - Specifying Test Namespace - :test-ns"
+  (clojure.test/testing  "doc/example.adoc - line 220 - Specifying Test Namespace - :test-ns"
 ;; this code block will generate tests under example-adoc-new-ns.ns1-test
 
 nil

test-resources/expected/test-doc-blocks/test/example_adoc_new_ns_test.cljc

@@ -5,7 +5,7 @@
             #?(:clj lread.test-doc-blocks.runtime)))
 
 (clojure.test/deftest block-0001
-  (clojure.test/testing  "doc/example.adoc - line 199 - Specifying Test Namespace - :test-ns"
+  (clojure.test/testing  "doc/example.adoc - line 204 - Specifying Test Namespace - :test-ns"
 ;; this code block will generate tests under example-adoc-new-ns-test
 
 (clojure.test/is (= '8 (* 2 4)))))