From: Mathias Lafeldt <misfire@debugon.org>
Date: Mon, 25 Apr 2011 18:30:22 GMT
Subject: Re: [PATCH] t/README: unify documentation of test function args
Message-ID: <4DB5BDBE.308@debugon.org>
In-Reply-To: <7v62q2l3ft.fsf@alter.siamese.dyndns.org>

[...] 
> 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
	'

>> @@ -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