{"thread":{"id":"27166","subject":"[PATCH] t/README: unify documentation of test function args","startedAt":"2011-04-24T10:52:59Z","lastAt":"2011-04-27T04:44:38Z","messageCount":7,"participants":["Mathias Lafeldt","Junio C Hamano","Drew Northup"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"166275","messageId":"4DB4010B.6080804@debugon.org","threadId":"27166","inReplyTo":null,"subject":"[PATCH] t/README: unify documentation of test function args","fromName":"Mathias Lafeldt","fromEmail":"misfire@debugon.org","sentAt":"2011-04-24T10:52:59Z","receivedAt":"2011-04-24T10:52:59Z","isPatch":true,"sender":{"key":"misfire@debugon.org","avatar":"https://avatars.githubusercontent.com/u/158074?v=4"},"body":"Document all test function arguments in the same way.\n\nWhile at it, correct some grammatical errors.\n\nSigned-off-by: Mathias Lafeldt <misfire@debugon.org>\n---\n t/README |   26 +++++++++++++-------------\n 1 files changed, 13 insertions(+), 13 deletions(-)\n\ndiff --git a/t/README b/t/README\nindex 428ee05..e8372d7 100644\n--- a/t/README\n+++ b/t/README\n@@ -379,7 +379,7 @@ library for your script to use.\n \n  - test_expect_success [<prereq>] <message> <script>\n \n-   Usually takes two strings as parameter, and evaluates the\n+   Usually takes two strings as parameters, and evaluates the\n    <script>.  If it yields success, test is considered\n    successful.  <message> should state what it is testing.\n \n@@ -389,7 +389,7 @@ library for your script to use.\n \t    'git-write-tree should be able to write an empty tree.' \\\n \t    'tree=$(git-write-tree)'\n \n-   If you supply three parameters the first will be taken to be a\n+   If you supply three parameters, the first will be taken to be a\n    prerequisite, see the test_set_prereq and test_have_prereq\n    documentation below:\n \n@@ -446,7 +446,7 @@ library for your script to use.\n    Merges the given rev using the given message.  Like test_commit,\n    creates a tag and calls test_tick before committing.\n \n- - test_set_prereq SOME_PREREQ\n+ - test_set_prereq <prereq>\n \n    Set a test prerequisite to be used later with test_have_prereq. The\n    test-lib will set some prerequisites for you, see the\n@@ -456,7 +456,7 @@ library for your script to use.\n    test_have_prereq directly, or the three argument invocation of\n    test_expect_success and test_expect_failure.\n \n- - test_have_prereq SOME PREREQ\n+ - test_have_prereq <prereq>\n \n    Check if we have a prerequisite previously set with\n    test_set_prereq. The most common use of this directly is to skip\n@@ -503,18 +503,18 @@ library for your script to use.\n \t\ttest_expect_code 1 git merge \"merge msg\" B master\n \t'\n \n- - test_must_fail <git-command>\n+ - test_must_fail <command>\n \n-   Run a git command and ensure it fails in a controlled way.  Use\n-   this instead of \"! <git-command>\".  When git-command dies due to a\n-   segfault, test_must_fail diagnoses it as an error; \"! <git-command>\"\n-   treats it as just another expected failure, which would let such a\n-   bug go unnoticed.\n+   Run a command and ensure it fails in a controlled way.  Use this\n+   instead of \"! <command>\".  When the command dies due to a segfault,\n+   test_must_fail diagnoses it as an error; \"! <command>\" treats it as\n+   just another expected failure, which would let such a bug go\n+   unnoticed.\n \n- - test_might_fail <git-command>\n+ - test_might_fail <command>\n \n    Similar to test_must_fail, but tolerate success, too.  Use this\n-   instead of \"<git-command> || :\" to catch failures due to segv.\n+   instead of \"<command> || :\" to catch failures due to segfault.\n \n  - test_cmp <expected> <actual>\n \n@@ -530,7 +530,7 @@ library for your script to use.\n    test_path_is_dir <dir> [<diagnosis>]\n    test_path_is_missing <path> [<diagnosis>]\n \n-   Check whether a file/directory exists or doesn't. <diagnosis> will\n+   Check whether a file/directory exists or not. <diagnosis> will\n    be displayed if the test fails.\n \n  - test_when_finished <script>\n-- \n1.7.5.rc3\n"},{"id":"166314","messageId":"7v62q2l3ft.fsf@alter.siamese.dyndns.org","threadId":"27166","inReplyTo":"4DB4010B.6080804@debugon.org","subject":"Re: [PATCH] t/README: unify documentation of test function args","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-04-25T16:07:50Z","receivedAt":"2011-04-25T16:07:50Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Mathias Lafeldt <misfire@debugon.org> writes:\n\n> Document all test function arguments in the same way.\n>\n> While at it, correct some grammatical errors.\n>\n> Signed-off-by: Mathias Lafeldt <misfire@debugon.org>\n\nThanks.\n\n> diff --git a/t/README b/t/README\n> index 428ee05..e8372d7 100644\n> --- a/t/README\n> +++ b/t/README\n\nEverything before this hunk looks sensible.\n\n> @@ -503,18 +503,18 @@ library for your script to use.\n>  \t\ttest_expect_code 1 git merge \"merge msg\" B master\n>  \t'\n>  \n> - - test_must_fail <git-command>\n> + - test_must_fail <command>\n> ...  \n> +   Run a command and ensure it fails in a controlled way.  Use this\n> +   instead of \"! <command>\".  When the command dies due to a segfault,\n> +   test_must_fail diagnoses it as an error; \"! <command>\" treats it as\n> +   just another expected failure, which would let such a bug go\n> +   unnoticed.\n>  \n> - - test_might_fail <git-command>\n> + - test_might_fail <command>\n>  \n>     Similar to test_must_fail, but tolerate success, too...\n\nBut the above two deliberately say \"git-command\" to clarify that these are\nspecial cases and meant to be used only to run a git command.  If we\nexpect a failure from a command that is not \"git\", say \"date\", we would\nwant to say \"! date\", not \"test_must_fail date\".\n\n> @@ -530,7 +530,7 @@ library for your script to use.\n>     test_path_is_dir <dir> [<diagnosis>]\n>     test_path_is_missing <path> [<diagnosis>]\n>  \n> -   Check whether a file/directory exists or doesn't. <diagnosis> will\n> +   Check whether a file/directory exists or not. <diagnosis> will\n\nIs the original really a grammo, or is this change just your personal\ntaste?  If I were rewriting this, I would probably say something like:\n\n\t- test_path_is_file <path> [<diagnosis>]\n          test_path_is_dir <path> [<diagnosis>]\n          test_path_is_missing <path> [<diagnosis>]\n\n\t  Check if the named path is a file, if the named path is a\n          directory, or if the named path does not exist, respectively,\n          and fail otherwise, showing the <diagnosis> text.\n"},{"id":"166322","messageId":"4DB5BDBE.308@debugon.org","threadId":"27166","inReplyTo":"7v62q2l3ft.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] t/README: unify documentation of test function args","fromName":"Mathias Lafeldt","fromEmail":"misfire@debugon.org","sentAt":"2011-04-25T18:30:22Z","receivedAt":"2011-04-25T18:30:22Z","isPatch":true,"sender":{"key":"misfire@debugon.org","avatar":"https://avatars.githubusercontent.com/u/158074?v=4"},"body":"[...] \n> Everything before this hunk looks sensible.\n> \n>> @@ -503,18 +503,18 @@ library for your script to use.\n>>  \t\ttest_expect_code 1 git merge \"merge msg\" B master\n>>  \t'\n>>  \n>> - - test_must_fail <git-command>\n>> + - test_must_fail <command>\n>> ...  \n>> +   Run a command and ensure it fails in a controlled way.  Use this\n>> +   instead of \"! <command>\".  When the command dies due to a segfault,\n>> +   test_must_fail diagnoses it as an error; \"! <command>\" treats it as\n>> +   just another expected failure, which would let such a bug go\n>> +   unnoticed.\n>>  \n>> - - test_might_fail <git-command>\n>> + - test_might_fail <command>\n>>  \n>>     Similar to test_must_fail, but tolerate success, too...\n> \n> But the above two deliberately say \"git-command\" to clarify that these are\n> special cases and meant to be used only to run a git command.  If we\n> expect a failure from a command that is not \"git\", say \"date\", we would\n> want to say \"! date\", not \"test_must_fail date\".\n> \n\nAh, okay. Is this true for test_expect_code too? It also has a git command\nin the example, but it says <command>, not <git-command>:\n\n - test_expect_code <exit-code> <command>\n\n   Run a command and ensure that it exits with the given exit code.\n   For example:\n\n\ttest_expect_success 'Merge with d/f conflicts' '\n\t\ttest_expect_code 1 git merge \"merge msg\" B master\n\t'\n\n>> @@ -530,7 +530,7 @@ library for your script to use.\n>>     test_path_is_dir <dir> [<diagnosis>]\n>>     test_path_is_missing <path> [<diagnosis>]\n>>  \n>> -   Check whether a file/directory exists or doesn't. <diagnosis> will\n>> +   Check whether a file/directory exists or not. <diagnosis> will\n> \n> Is the original really a grammo, or is this change just your personal\n> taste?  If I were rewriting this, I would probably say something like:\n> \n> \t- test_path_is_file <path> [<diagnosis>]\n>           test_path_is_dir <path> [<diagnosis>]\n>           test_path_is_missing <path> [<diagnosis>]\n> \n> \t  Check if the named path is a file, if the named path is a\n>           directory, or if the named path does not exist, respectively,\n>           and fail otherwise, showing the <diagnosis> text.\n\nYes, it's just a matter of taste, but your rewrite is even better.\n\n-Mathias\n"},{"id":"166325","messageId":"7vzknei0vn.fsf@alter.siamese.dyndns.org","threadId":"27166","inReplyTo":"4DB5BDBE.308@debugon.org","subject":"Re: [PATCH] t/README: unify documentation of test function args","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-04-25T19:31:24Z","receivedAt":"2011-04-25T19:31:24Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Mathias Lafeldt <misfire@debugon.org> writes:\n\n> Ah, okay. Is this true for test_expect_code too? It also has a git command\n> in the example, but it says <command>, not <git-command>:\n>\n>  - test_expect_code <exit-code> <command>\n\nI think that one is Ok as there is no git specific hacks in the semantics.\nIt is a straight \"Run this command, and make sure you get this exit code\".\n\nThe \"must-fail\" is really a special case in that we just do not expect any\nfailure, but expect a controlled failure.  Currently we only catch segv,\nbut we should anticipate that we will reject other types of uncontrolled\nfailures in the future, and keeping the function \"git-only\" makes it\neasier to manage.\n"},{"id":"166369","messageId":"1303814006-4109-1-git-send-email-misfire@debugon.org","threadId":"27166","inReplyTo":"7vzknei0vn.fsf@alter.siamese.dyndns.org","subject":"[PATCH v2] t/README: unify documentation of test function args","fromName":"Mathias Lafeldt","fromEmail":"misfire@debugon.org","sentAt":"2011-04-26T10:33:26Z","receivedAt":"2011-04-26T10:33:26Z","isPatch":true,"sender":{"key":"misfire@debugon.org","avatar":"https://avatars.githubusercontent.com/u/158074?v=4"},"body":"Document all test function arguments in the same way.\n\nWhile at it, tweak the description of test_path_is_* (thanks to Junio),\nand correct some grammatical errors.\n\nSigned-off-by: Mathias Lafeldt <misfire@debugon.org>\n---\n t/README |   17 +++++++++--------\n 1 files changed, 9 insertions(+), 8 deletions(-)\n\ndiff --git a/t/README b/t/README\nindex 428ee05..a90b043 100644\n--- a/t/README\n+++ b/t/README\n@@ -379,7 +379,7 @@ library for your script to use.\n \n  - test_expect_success [<prereq>] <message> <script>\n \n-   Usually takes two strings as parameter, and evaluates the\n+   Usually takes two strings as parameters, and evaluates the\n    <script>.  If it yields success, test is considered\n    successful.  <message> should state what it is testing.\n \n@@ -389,7 +389,7 @@ library for your script to use.\n \t    'git-write-tree should be able to write an empty tree.' \\\n \t    'tree=$(git-write-tree)'\n \n-   If you supply three parameters the first will be taken to be a\n+   If you supply three parameters, the first will be taken to be a\n    prerequisite, see the test_set_prereq and test_have_prereq\n    documentation below:\n \n@@ -446,7 +446,7 @@ library for your script to use.\n    Merges the given rev using the given message.  Like test_commit,\n    creates a tag and calls test_tick before committing.\n \n- - test_set_prereq SOME_PREREQ\n+ - test_set_prereq <prereq>\n \n    Set a test prerequisite to be used later with test_have_prereq. The\n    test-lib will set some prerequisites for you, see the\n@@ -456,7 +456,7 @@ library for your script to use.\n    test_have_prereq directly, or the three argument invocation of\n    test_expect_success and test_expect_failure.\n \n- - test_have_prereq SOME PREREQ\n+ - test_have_prereq <prereq>\n \n    Check if we have a prerequisite previously set with\n    test_set_prereq. The most common use of this directly is to skip\n@@ -526,12 +526,13 @@ library for your script to use.\n \n    Check whether a file has the length it is expected to.\n \n- - test_path_is_file <file> [<diagnosis>]\n-   test_path_is_dir <dir> [<diagnosis>]\n+ - test_path_is_file <path> [<diagnosis>]\n+   test_path_is_dir <path> [<diagnosis>]\n    test_path_is_missing <path> [<diagnosis>]\n \n-   Check whether a file/directory exists or doesn't. <diagnosis> will\n-   be displayed if the test fails.\n+   Check if the named path is a file, if the named path is a\n+   directory, or if the named path does not exist, respectively,\n+   and fail otherwise, showing the <diagnosis> text.\n \n  - test_when_finished <script>\n \n-- \n1.7.5\n"},{"id":"166398","messageId":"1303839041.18603.17.camel@drew-northup.unet.maine.edu","threadId":"27166","inReplyTo":"1303814006-4109-1-git-send-email-misfire@debugon.org","subject":"Re: [PATCH v2] t/README: unify documentation of test function args","fromName":"Drew Northup","fromEmail":"drew.northup@maine.edu","sentAt":"2011-04-26T17:30:41Z","receivedAt":"2011-04-26T17:30:41Z","isPatch":true,"sender":{"key":"drew.northup@maine.edu","avatar":"https://avatars.githubusercontent.com/u/18331571?v=4"},"body":"\nOn Tue, 2011-04-26 at 12:33 +0200, Mathias Lafeldt wrote:\n\n> @@ -389,7 +389,7 @@ library for your script to use.\n>  \t    'git-write-tree should be able to write an empty tree.' \\\n>  \t    'tree=$(git-write-tree)'\n>  \n> -   If you supply three parameters the first will be taken to be a\n> +   If you supply three parameters, the first will be taken to be a\n>     prerequisite, see the test_set_prereq and test_have_prereq\n>     documentation below:\n\nAs \"If you supply three parameters\" is not an introductory clause to a\nlarger complete thought in the following few words, the additional comma\nis unnecessary.\n\n-- \n-Drew Northup\n________________________________________________\n\"As opposed to vegetable or mineral error?\"\n-John Pescatore, SANS NewsBites Vol. 12 Num. 59\n"},{"id":"166447","messageId":"7vei4ob8w9.fsf@alter.siamese.dyndns.org","threadId":"27166","inReplyTo":"1303839041.18603.17.camel@drew-northup.unet.maine.edu","subject":"Re: [PATCH v2] t/README: unify documentation of test function args","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-04-27T04:44:38Z","receivedAt":"2011-04-27T04:44:38Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Drew Northup <drew.northup@maine.edu> writes:\n\n> On Tue, 2011-04-26 at 12:33 +0200, Mathias Lafeldt wrote:\n>\n>> @@ -389,7 +389,7 @@ library for your script to use.\n>>  \t    'git-write-tree should be able to write an empty tree.' \\\n>>  \t    'tree=$(git-write-tree)'\n>>  \n>> -   If you supply three parameters the first will be taken to be a\n>> +   If you supply three parameters, the first will be taken to be a\n>>     prerequisite, see the test_set_prereq and test_have_prereq\n>>     documentation below:\n>\n> As \"If you supply three parameters\" is not an introductory clause to a\n> larger complete thought in the following few words, the additional comma\n> is unnecessary.\n\nMakes sense.\n\nOn the other hand, \"see the ... below\" is a separate sentence, and it\ndeserves to have something stronger than a comma in front of it.  I've\nqueued with a minor fixup.\n\nThanks.\n"}]}