RFC patchtest-lib: move comment about test_description

When a comment describing how each test file should start was added in commit [1], it was the second comment of t/test-lib.sh. The comment describes how variable "test_description" is supposed to be assigned at the top of each test file. However, even in [1], the comment was ten lines away from the usage of the variable by test-lib.sh. Since then, the comment has drifted away both from the top of the file and from the usage of the variable. The comment just sits in the middle of the initialization of the test library, surrounded by unrelated code.

Move the comment describing how variable "test_description" is supposed to be assigned to just above the usage of the variable in test-lib.sh.

An alternative is to just drop this comment, since assignment of "test_description" and the process of writing tests in general are described in detail in "t/README".

[1] e1970ce43a ("[PATCH 1/2] Test framework take two.", 2005-05-13)

Signed-off-by: Andrei Rybak <rybak.a.v@gmail.com>
---
 t/test-lib.sh | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

When a comment describing how each test file should start was added in commit [1], it was the second comment of t/test-lib.sh. The comment describes how variable "test_description" is supposed to be assigned at the top of each test file. However, even in [1], the comment was ten lines away from the usage of the variable by test-lib.sh. Since then, the comment has drifted away both from the top of the file and from the usage of the variable. The comment just sits in the middle of the initialization of the test library, surrounded by unrelated code, almost one hundred lines away from the usage of "test_description".

Nobody has noticed this drift during evolution of test-lib.sh, which suggests that this comment has outlived its usefulness. The assignment of "test_description" and the process of writing tests in general are described in detail in "t/README". So drop the obsolete comment.

An alternative solution is to move the comment down to the usage of variable "test_description".

[1] e1970ce43a ("[PATCH 1/2] Test framework take two.", 2005-05-13)

Signed-off-by: Andrei Rybak <rybak.a.v@gmail.com>
---

  On 2023-02-22T00:22, Andrei Rybak wrote:
  > Move the comment describing how variable "test_description" is supposed
  > to be assigned to just above the usage of the variable in test-lib.sh.
  > 
  > An alternative is to just drop this comment, since assignment of
  > "test_description" and the process of writing tests in general are
  > described in detail in "t/README".

Here's the alternative solution described in the commit message of v1. I put the RFC tag in the subject, because I'm not sure which of the two approaches -- move in v1 or drop in v2 -- is better.

 t/test-lib.sh | 6 ------
 1 file changed, 6 deletions(-)

Andrei Rybak <rybak.a.v@gmail.com> writes:

Sounds sensible.

Or at the beginning, as the comment is about "how you can use this test-lib.sh test library in your tests".

I have no strong preference. Just dropping it sounds easier, as a more readable description already exists elsewhere.

When a comment describing how each test file should start was added in commit [1], it was the second comment of t/test-lib.sh. The comment describes how variable "test_description" is supposed to be assigned at the top of each test file and how "test-lib.sh" should be used by sourcing it. However, even in [1], the comment was ten lines away from the usage of the variable by test-lib.sh. Since then, the comment has drifted away both from the top of the file and from the usage of the variable. The comment just sits in the middle of the initialization of the test library, surrounded by unrelated code, almost one hundred lines away from the usage of "test_description".

Nobody has noticed this drift during evolution of test-lib.sh, which suggests that this comment has outlived its usefulness. The assignment of "test_description", sourcing of "test-lib.sh" by tests, and the process of writing tests in general are described in detail in "t/README". So drop the obsolete comment.

An alternative solution could be to move the comment either to the top of the file, or down to the usage of variable "test_description".

[1] e1970ce43a ("[PATCH 1/2] Test framework take two.", 2005-05-13)

Signed-off-by: Andrei Rybak <rybak.a.v@gmail.com>
---

  On 2023-02-25T23:50, Junio C Hamano wrote:
  > Andrei Rybak <rybak.a.v@gmail.com> writes:
  >> An alternative solution is to move the comment down to the usage of
  >> variable "test_description".
  > 
  > Or at the beginning, as the comment is about "how you can use this
  > test-lib.sh test library in your tests".

Here's v3 with updated description of the dropped comment and updated description of the alternative solution.

  > I have no strong preference.  Just dropping it sounds easier, as a
  > more readable description already exists elsewhere.

Also, at the top of "test-lib.sh", there is a comment pointing to that other place:

  # Test framework for git.  See t/README for usage.

added in c74c72034f (test: replace shebangs with descriptions in shell libraries, 2013-11-25).

 t/test-lib.sh | 6 ------
 1 file changed, 6 deletions(-)