makeRelative: document the laws

[hasufell]

In GitLab by @abel on Oct 10, 2022, 20:58

See https://hackage.haskell.org/package/filepath-1.4.100.0/docs/System-FilePath.html#v:makeRelative .
I would intuitively have expected makeRelative to be a partial inverse to </>, so that the following law holds:

  (makeRelative root path == Just rest)  ==  (root </> rest == path)

However, the actual function is total and we have makeRelative root path = path whenever we should actually get makeRelative root path = Nothing. But also, we have e.g. makeRelative "." path = path.

So, what would actually the laws be that specify makeRelative? And, could they please be added to the documentation?

[hasufell]

In GitLab by @maerwald on Oct 10, 2022, 21:28

We document the behavior via doctests. It allows unit test cases and properties. So feel free to augment it with your examples. Then run make to regenerate the tests.