Skip to contentSkip to conversation

t/README: link to metacpan.org, not search.cpan.org

PATCH In review Ævar Arnfjörð Bjarmason 3 participants 5 messages Mar 22, 2017 – Mar 24, 2017

lore
Share & tools
lore
#0 lore raw

PATCH 1/3 t/README: link to metacpan.org, not search.cpan.org

Change a link to the web version of the TAP::Parser::Grammar documentation to link to metacpan.org instead of search.cpan.org.

This is something I added back in commit 20873f45e7 ("t/README:
Document the do's and don'ts of tests", 2010-07-02), at the time search.cpan.org was the more actively maintained CPAN web-interface, nowadays that's metacpan.org.

---
 t/README | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
t/README +1 -1
index 4982d1c521..a50290c789 100644
@@ -471,7 +471,7 @@ Don't:
    their output.
 
    You can glean some further possible issues from the TAP grammar
-   (see http://search.cpan.org/perldoc?TAP::Parser::Grammar#TAP_Grammar)
+   (see https://metacpan.org/pod/TAP::Parser::Grammar#TAP-GRAMMAR)
    but the best indication is to just run the tests with prove(1),
    it'll complain if anything is amiss.
 
Signature · 1 line
2.11.0
#1 lore raw

PATCH 2/3 t/README: change "Inside <X> part" to "Inside the <X> part"

Change the mention of "Inside the <script> part, the standard output..." to use the definite article, which makes more sense in this context.

This changes documentation I originally added back in commit 20873f45e7 ("t/README: Document the do's and don'ts of tests", 2010-07-02).

---
 t/README | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
t/README +1 -1
index a50290c789..89512e23d4 100644
@@ -477,7 +477,7 @@ Don't:
 
 Keep in mind:
 
- - Inside <script> part, the standard output and standard error
+ - Inside the <script> part, the standard output and standard error
    streams are discarded, and the test harness only reports "ok" or
    "not ok" to the end user running the tests. Under --verbose, they
    are shown to help debugging the tests.
Signature · 1 line
2.11.0
#2 lore raw

PATCH 3/3 t/README: clarify the test_have_prereq documentation

In reply to Ævar Arnfjörð Bjarmason

Clarify the test_have_prereq documentation so that it's clear in the reader's mind when the text says "most common use of this directly" what the answer to "as opposed to what?" is.

Usually this function isn't used in lieu of using the prerequisite support built into test_expect_*, mention that explicitly.

This changes documentation that I added in commit 9a897893a7 ("t/README: Document the prereq functions, and 3-arg test_*", 2010-07-02).

---
 t/README | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)
t/README +4 -2
index 89512e23d4..36813cef94 100644
@@ -612,8 +612,10 @@ library for your script to use.
  - test_have_prereq <prereq>
 
    Check if we have a prerequisite previously set with
-   test_set_prereq. The most common use of this directly is to skip
-   all the tests if we don't have some essential prerequisite:
+   test_set_prereq. The most common use-case for using this directly,
+   as opposed to as an argument to test_expect_*, is to skip all the
+   tests at the start of the test script if we don't have some
+   essential prerequisite:
 
 	if ! test_have_prereq PERL
 	then
Signature · 1 line
2.11.0
Reviewed-by on v1 3/3
#3 lore raw

Re: [PATCH 3/3] t/README: clarify the test_have_prereq documentation

Hi,

t/README library for your script to use. · line 618

Quoted 12 lines · Ævar Arnfjörð Bjarmason
t/README +4 -2
@@ -612,8 +612,10 @@ library for your script to use.
  - test_have_prereq <prereq>
 
    Check if we have a prerequisite previously set with
-   test_set_prereq. The most common use of this directly is to skip
-   all the tests if we don't have some essential prerequisite:
+   test_set_prereq. The most common use-case for using this directly,
+   as opposed to as an argument to test_expect_*, is to skip all the
+   tests at the start of the test script if we don't have some
+   essential prerequisite:

Nit: the hyphenated word "use-case" feels jargon-ish. I've seen it more often as two separate words. Better yet to clarify that we're talking about idioms and not just goals:

The most common way to use this explicitly (as opposed
to the implicit use when an argument is passed to test_expect_*) is to skip all the tests at the start of a test script if we don't have some essential prerequisite:

With or without such a change,

Thanks.