Apply suggestions from code review

Co-authored-by: Valentin Gagarin <[email protected]>

doc/manual/src/contributing/testing.md

@@ -2,7 +2,7 @@
 
 ## Unit-tests
 
-The unit-tests for defined using the [googletest] and [rapidcheck] frameworks.
+The unit-tests are defined using the [googletest] and [rapidcheck] frameworks.
 
 [googletest]: https://google.github.io/googletest/
 [rapidcheck]: https://github.com/emil-e/rapidcheck
@@ -30,16 +30,21 @@ The unit-tests for defined using the [googletest] and [rapidcheck] frameworks.
 > ```
 
 The tests for each Nix library (`libnixexpr`, `libnixstore`, etc..) live inside a directory `src/${library_name_without-nix}-tests` next to the directory for the library (`src/${library_name_without-nix}`).
-Given a interface (header) and implementation pair in the original library, say, `value/context.{hh,cc}`, we write tests for it in `value/context.cc`, and (possibly) declare additional interfaces for testing purposes in `test/value/context.hh`.
-(Note only the extra header is nested inside the `test` directory. This is explained further below.)
+Given a interface (header) and implementation pair in the original library, say, `libexpr/value/context.{hh,cc}`, we write tests for it in `libexpr-tests/value/context.cc`, and (possibly) declare additional interfaces for testing purposes in `libexpr-tests/tests/value/context.hh`.
+
+> **Note**
+>
+> Only the extra header is nested inside the `test` directory. This is explained further below.
+
+### Rationale
 
 The use of a separate directory for the unit tests might seem inconvenient, as the tests are not "right next to" the part of the code they are testing.
 But organizing the tests this way has one big benefit:
 there is no risk of any build-system wildcards for the library accidentally picking up test code that shoud not built and installed as part of the library.
 
 Likewise, the use of the `test/` subdir might seem superfluous:
 Isn't the point of the `*-test` subdir to indicate that these files are tests?
-Why do we need another `test` subdir too?
+Why do we need another `test` subdirectory?
 The answer is that we need to be able to tell apart the two headers, and make sure we include the right one.
 For `.cc` files, this is matter of doing `#include "foo.hh"` vs `#include "tests/foo.hh`
 For `.hh` files, this is a bit more subtle, because a `#include "foo.hh` instead `tests/foo.hh` will end up including itself because `#include "..."`
@@ -48,8 +53,8 @@ Instead, use `#include <foo.hh>` to get the original library header, and `#inclu
 
 Why do we have test headers at all?
 These are usually for [rapidcheck]'s `Arbitrary` machinery, which is used to describe how to generate values of a given type for the sake of running property tests.
-Because types contain other types, `Arbitrary "instances" for some type are not just useful for testing that type, but also any other type that contains it.
-(Indeed, if we don't reuse the upstream type's `Arbitrary` instance, the downstream type's `Arbitrary` instance would become much more complex and hard to understand.)
+Because types contain other types, `Arbitrary` "instances" for some type are not just useful for testing that type, but also any other type that contains it.
+Indeed, if we don't reuse the upstream type's `Arbitrary` instance, the downstream type's `Arbitrary` instance would become much more complex and hard to understand.
 In order to reuse these instances, we therefore declare them in these testing headers.
 
 ### Running tests