threads / patch / 27166

patcht/README: unify documentation of test function args

Subject: [PATCH] t/README: unify documentation of test function args

## tl;dr

7 messages between Apr 24, 2011 and Apr 27, 2011. Diffs are folded; open one to read it.

replies: 6people: 3as markdown or json

Mathias Lafeldt· Apr 24, 2011, 10:52 UTC · lore
Document all test function arguments in the same way.
While at it, correct some grammatical errors.
Signed-off-by: Mathias Lafeldt <misfire@debugon.org>
---
 t/README |   26 +++++++++++++-------------
 1 files changed, 13 insertions(+), 13 deletions(-)
Show changes to t/README +13 −13
diff --git a/t/README b/t/README
index 428ee05..e8372d7 100644
--- a/t/README
+++ b/t/README
@@ -379,7 +379,7 @@ library for your script to use.
 
  - test_expect_success [<prereq>] <message> <script>
 
-   Usually takes two strings as parameter, and evaluates the
+   Usually takes two strings as parameters, and evaluates the
    <script>.  If it yields success, test is considered
    successful.  <message> should state what it is testing.
 
@@ -389,7 +389,7 @@ library for your script to use.
 	    'git-write-tree should be able to write an empty tree.' \
 	    'tree=$(git-write-tree)'
 
-   If you supply three parameters the first will be taken to be a
+   If you supply three parameters, the first will be taken to be a
    prerequisite, see the test_set_prereq and test_have_prereq
    documentation below:
 
@@ -446,7 +446,7 @@ library for your script to use.
    Merges the given rev using the given message.  Like test_commit,
    creates a tag and calls test_tick before committing.
 
- - test_set_prereq SOME_PREREQ
+ - test_set_prereq <prereq>
 
    Set a test prerequisite to be used later with test_have_prereq. The
    test-lib will set some prerequisites for you, see the
@@ -456,7 +456,7 @@ library for your script to use.
    test_have_prereq directly, or the three argument invocation of
    test_expect_success and test_expect_failure.
 
- - test_have_prereq SOME PREREQ
+ - 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
@@ -503,18 +503,18 @@ library for your script to use.
 		test_expect_code 1 git merge "merge msg" B master
 	'
 
- - test_must_fail <git-command>
+ - test_must_fail <command>
 
-   Run a git command and ensure it fails in a controlled way.  Use
-   this instead of "! <git-command>".  When git-command dies due to a
-   segfault, test_must_fail diagnoses it as an error; "! <git-command>"
-   treats it as just another expected failure, which would let such a
-   bug go unnoticed.
+   Run a command and ensure it fails in a controlled way.  Use this
+   instead of "! <command>".  When the command dies due to a segfault,
+   test_must_fail diagnoses it as an error; "! <command>" treats it as
+   just another expected failure, which would let such a bug go
+   unnoticed.
 
- - test_might_fail <git-command>
+ - test_might_fail <command>
 
    Similar to test_must_fail, but tolerate success, too.  Use this
-   instead of "<git-command> || :" to catch failures due to segv.
+   instead of "<command> || :" to catch failures due to segfault.
 
  - test_cmp <expected> <actual>
 
@@ -530,7 +530,7 @@ library for your script to use.
    test_path_is_dir <dir> [<diagnosis>]
    test_path_is_missing <path> [<diagnosis>]
 
-   Check whether a file/directory exists or doesn't. <diagnosis> will
+   Check whether a file/directory exists or not. <diagnosis> will
    be displayed if the test fails.
 
  - test_when_finished <script>

-- 
1.7.5.rc3
Junio C Hamano· Apr 25, 2011, 16:07 UTC · re: Mathias Lafeldt · lore

Re: [PATCH] t/README: unify documentation of test function args

Mathias Lafeldt <misfire@debugon.org> writes:
Show 5 quoted lines
> Document all test function arguments in the same way.
>
> While at it, correct some grammatical errors.
>
> Signed-off-by: Mathias Lafeldt <misfire@debugon.org>
Thanks.
> diff --git a/t/README b/t/README
> index 428ee05..e8372d7 100644
> --- a/t/README
> +++ b/t/README
Everything before this hunk looks sensible.
Show 17 quoted lines
> @@ -503,18 +503,18 @@ library for your script to use.
>  		test_expect_code 1 git merge "merge msg" B master
>  	'
>  
> - - test_must_fail <git-command>
> + - test_must_fail <command>
> ...  
> +   Run a command and ensure it fails in a controlled way.  Use this
> +   instead of "! <command>".  When the command dies due to a segfault,
> +   test_must_fail diagnoses it as an error; "! <command>" treats it as
> +   just another expected failure, which would let such a bug go
> +   unnoticed.
>  
> - - test_might_fail <git-command>
> + - test_might_fail <command>
>  
>     Similar to test_must_fail, but tolerate success, too...

But the above two deliberately say "git-command" to clarify that these are special cases and meant to be used only to run a git command. If we expect a failure from a command that is not "git", say "date", we would want to say "! date", not "test_must_fail date".

Show 6 quoted lines
> @@ -530,7 +530,7 @@ library for your script to use.
>     test_path_is_dir <dir> [<diagnosis>]
>     test_path_is_missing <path> [<diagnosis>]
>  
> -   Check whether a file/directory exists or doesn't. <diagnosis> will
> +   Check whether a file/directory exists or not. <diagnosis> will

Is the original really a grammo, or is this change just your personal taste? If I were rewriting this, I would probably say something like:

	- test_path_is_file <path> [<diagnosis>]
          test_path_is_dir <path> [<diagnosis>]
          test_path_is_missing <path> [<diagnosis>]
	  Check if the named path is a file, if the named path is a
          directory, or if the named path does not exist, respectively,
          and fail otherwise, showing the <diagnosis> text.
Mathias Lafeldt· Apr 25, 2011, 18:30 UTC · re: Junio C Hamano · lore

Re: [PATCH] t/README: unify documentation of test function args

[...]
Show 25 quoted lines
> Everything before this hunk looks sensible.
> 
>> @@ -503,18 +503,18 @@ library for your script to use.
>>  		test_expect_code 1 git merge "merge msg" B master
>>  	'
>>  
>> - - test_must_fail <git-command>
>> + - test_must_fail <command>
>> ...  
>> +   Run a command and ensure it fails in a controlled way.  Use this
>> +   instead of "! <command>".  When the command dies due to a segfault,
>> +   test_must_fail diagnoses it as an error; "! <command>" treats it as
>> +   just another expected failure, which would let such a bug go
>> +   unnoticed.
>>  
>> - - test_might_fail <git-command>
>> + - test_might_fail <command>
>>  
>>     Similar to test_must_fail, but tolerate success, too...
> 
> But the above two deliberately say "git-command" to clarify that these are
> special cases and meant to be used only to run a git command.  If we
> expect a failure from a command that is not "git", say "date", we would
> want to say "! date", not "test_must_fail date".
>

Ah, okay. Is this true for test_expect_code too? It also has a git command in the example, but it says <command>, not <git-command>:

 - test_expect_code <exit-code> <command>
   Run a command and ensure that it exits with the given exit code.
   For example:
	test_expect_success 'Merge with d/f conflicts' '
		test_expect_code 1 git merge "merge msg" B master
	'
Show 17 quoted lines
>> @@ -530,7 +530,7 @@ library for your script to use.
>>     test_path_is_dir <dir> [<diagnosis>]
>>     test_path_is_missing <path> [<diagnosis>]
>>  
>> -   Check whether a file/directory exists or doesn't. <diagnosis> will
>> +   Check whether a file/directory exists or not. <diagnosis> will
> 
> Is the original really a grammo, or is this change just your personal
> taste?  If I were rewriting this, I would probably say something like:
> 
> 	- test_path_is_file <path> [<diagnosis>]
>           test_path_is_dir <path> [<diagnosis>]
>           test_path_is_missing <path> [<diagnosis>]
> 
> 	  Check if the named path is a file, if the named path is a
>           directory, or if the named path does not exist, respectively,
>           and fail otherwise, showing the <diagnosis> text.
Yes, it's just a matter of taste, but your rewrite is even better.
-Mathias
Junio C Hamano· Apr 25, 2011, 19:31 UTC · re: Mathias Lafeldt · lore

Re: [PATCH] t/README: unify documentation of test function args

Mathias Lafeldt <misfire@debugon.org> writes:
> Ah, okay. Is this true for test_expect_code too? It also has a git command
> in the example, but it says <command>, not <git-command>:
>
>  - test_expect_code <exit-code> <command>

I think that one is Ok as there is no git specific hacks in the semantics. It is a straight "Run this command, and make sure you get this exit code".

The "must-fail" is really a special case in that we just do not expect any failure, but expect a controlled failure. Currently we only catch segv, but we should anticipate that we will reject other types of uncontrolled failures in the future, and keeping the function "git-only" makes it easier to manage.

Mathias Lafeldt· Apr 26, 2011, 10:33 UTC · re: Junio C Hamano · lore

[PATCH v2] t/README: unify documentation of test function args

Document all test function arguments in the same way.

While at it, tweak the description of test_path_is_* (thanks to Junio), and correct some grammatical errors.

Signed-off-by: Mathias Lafeldt <misfire@debugon.org>
---
 t/README |   17 +++++++++--------
 1 files changed, 9 insertions(+), 8 deletions(-)
Show changes to t/README +9 −8
diff --git a/t/README b/t/README
index 428ee05..a90b043 100644
--- a/t/README
+++ b/t/README
@@ -379,7 +379,7 @@ library for your script to use.
 
  - test_expect_success [<prereq>] <message> <script>
 
-   Usually takes two strings as parameter, and evaluates the
+   Usually takes two strings as parameters, and evaluates the
    <script>.  If it yields success, test is considered
    successful.  <message> should state what it is testing.
 
@@ -389,7 +389,7 @@ library for your script to use.
 	    'git-write-tree should be able to write an empty tree.' \
 	    'tree=$(git-write-tree)'
 
-   If you supply three parameters the first will be taken to be a
+   If you supply three parameters, the first will be taken to be a
    prerequisite, see the test_set_prereq and test_have_prereq
    documentation below:
 
@@ -446,7 +446,7 @@ library for your script to use.
    Merges the given rev using the given message.  Like test_commit,
    creates a tag and calls test_tick before committing.
 
- - test_set_prereq SOME_PREREQ
+ - test_set_prereq <prereq>
 
    Set a test prerequisite to be used later with test_have_prereq. The
    test-lib will set some prerequisites for you, see the
@@ -456,7 +456,7 @@ library for your script to use.
    test_have_prereq directly, or the three argument invocation of
    test_expect_success and test_expect_failure.
 
- - test_have_prereq SOME PREREQ
+ - 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
@@ -526,12 +526,13 @@ library for your script to use.
 
    Check whether a file has the length it is expected to.
 
- - test_path_is_file <file> [<diagnosis>]
-   test_path_is_dir <dir> [<diagnosis>]
+ - test_path_is_file <path> [<diagnosis>]
+   test_path_is_dir <path> [<diagnosis>]
    test_path_is_missing <path> [<diagnosis>]
 
-   Check whether a file/directory exists or doesn't. <diagnosis> will
-   be displayed if the test fails.
+   Check if the named path is a file, if the named path is a
+   directory, or if the named path does not exist, respectively,
+   and fail otherwise, showing the <diagnosis> text.
 
  - test_when_finished <script>
 

-- 
1.7.5
Drew Northup· Apr 26, 2011, 17:30 UTC · re: Mathias Lafeldt · lore

Re: [PATCH v2] t/README: unify documentation of test function args

On Tue, 2011-04-26 at 12:33 +0200, Mathias Lafeldt wrote:
Show 8 quoted lines
> @@ -389,7 +389,7 @@ library for your script to use.
>  	    'git-write-tree should be able to write an empty tree.' \
>  	    'tree=$(git-write-tree)'
>  
> -   If you supply three parameters the first will be taken to be a
> +   If you supply three parameters, the first will be taken to be a
>     prerequisite, see the test_set_prereq and test_have_prereq
>     documentation below:

As "If you supply three parameters" is not an introductory clause to a larger complete thought in the following few words, the additional comma is unnecessary.

-- 
-Drew Northup
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59
Junio C Hamano· Apr 27, 2011, 04:44 UTC · re: Drew Northup · lore

Re: [PATCH v2] t/README: unify documentation of test function args

Drew Northup <drew.northup@maine.edu> writes:
Show 14 quoted lines
> On Tue, 2011-04-26 at 12:33 +0200, Mathias Lafeldt wrote:
>
>> @@ -389,7 +389,7 @@ library for your script to use.
>>  	    'git-write-tree should be able to write an empty tree.' \
>>  	    'tree=$(git-write-tree)'
>>  
>> -   If you supply three parameters the first will be taken to be a
>> +   If you supply three parameters, the first will be taken to be a
>>     prerequisite, see the test_set_prereq and test_have_prereq
>>     documentation below:
>
> As "If you supply three parameters" is not an introductory clause to a
> larger complete thought in the following few words, the additional comma
> is unnecessary.
Makes sense.

On the other hand, "see the ... below" is a separate sentence, and it deserves to have something stronger than a comma in front of it. I've queued with a minor fixup.

Thanks.

← back to recent threads