[commit: packages/filepath] RyanGlScott-patch-1, master: Add developer notes (ffa89a6)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/filepath

On branches: RyanGlScott-patch-1,master
Link       : http://git.haskell.org/packages/filepath.git/commitdiff/ffa89a641797dffcb1586d5ce1c01835c0f6a441

>---------------------------------------------------------------

commit ffa89a641797dffcb1586d5ce1c01835c0f6a441
Author: Neil Mitchell <ndmitchell at gmail.com>
Date:   Sat Aug 19 22:45:15 2017 +0100

    Add developer notes


>---------------------------------------------------------------

ffa89a641797dffcb1586d5ce1c01835c0f6a441
 README.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/README.md b/README.md
index f059998..0b1c442 100644
--- a/README.md
+++ b/README.md
@@ -17,3 +17,17 @@ The answer for this library is "no". While an abstract `FilePath` has some advan
 * Often it is useful to represent invalid files, e.g. `/foo/*.txt` probably isn't an actual file, but a glob pattern. Other programs use `foo//bar` for globs, which is definitely not a file, but might want to be stored as a `FilePath`.
 * Some programs use syntactic non-semantic details of the `FilePath` to change their behaviour. For example, `foo`, `foo/` and `foo/.` are all similar, and refer to the same location on disk, but may behave differently when passed to command-line tools.
 * A useful step to introducing an abstract `FilePath` is to reduce the amount of manipulating `FilePath` values like lists. This library hopes to help in that effort.
+
+### Developer notes
+
+Most of the code is in `System/FilePath/Internal.hs` which is `#include`'d into both `System/FilePath/Posix.hs` and `System/FilePath/Windows.hs` with the `IS_WINDOWS` CPP define set to either `True` or `False`. This Internal module is a bit weird in that it isn't really a Haskell module, but is more an include file.
+
+The library has extensive doc tests. Anything starting with `-- >` is transformed into a doc test as a predicate that must evaluate to `True`. These tests follow a few rules:
+
+* Tests prefixed with `Windows:` or `Posix:` are only tested against that specific implementation - otherwise tests are run against both implementations.
+* Any single letter variable, e.g. `x`, is considered universal quantification, and is checked with `QuickCheck`.
+* If `Valid x =>` appears at the start of a doc test, that means the property will only be tested with `x` passing the `isValid` predicate.
+
+The tests can be generated by `Generate.hs` in the root of the repo, and will be placed in `tests/TestGen.hs`. The `TestGen.hs` file is checked into the repo, and the CI scripts check that `TestGen.hs` is in sync with what would be generated a fresh - if you don't regenerate `TestGen.hs` the CI will fail.
+
+The `.ghci` file is set up to allow you to type `ghci` to open the library, then `:go` will regenerate the tests and run them.