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

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 25, 2011, 16:07 UTC
Message-ID: <7v62q2l3ft.fsf@alter.siamese.dyndns.org>
In-Reply-To: <4DB4010B.6080804@debugon.org>

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.