Path's .relativize documentation is wrong on a crucial point

[Francis Galiegue]

Let us have a FileSystemProvider which provides FileSystems with
Unix-like Paths.

Let us have two FileSystems from that same provider fs1 and fs2.

Let us have p issued from FileSystem fs1 which is "a".

Let us have q issued from FileSystem fs2 which is "b".

Let us call r the result of p.resolve(q). Since this is a Unix-like
filesystem, none of p and q have root components (that would be /),
and the resulting path r would be "a/b", on filesystem fs1.

Now, let us do:

p.relativize(r)

Both p (which is "a") and r (which is "a/b") are on fs1; the result is
"b", which is on... fs1.

Which contradicts the equality of the Path's .relativize() which says that:

----

For any two normalized paths p and q, where q does not have a root component,

    p.relativize(p.resolve(q)).equals(q)
----

This is clearly not true in this case. Path's .equals() says it explicitly.

And this was easy to demonstrate, without even an implementation...

Now, case in point: I have implemented JSR 203 for both DropBox and
FTP where this just cannot be true: I can issue several FileSystems
from the same providers (one for DropBox, the other for FTP) for which
even _trying to resolve_ Paths from different FileSystems but the same
provider does not make any sense at all (you may end up accessing _the
wrong entity altogether_); this is why I define
FileSystemMismatchException.

I consider this to be a bug in the API definition. What do you think?

Regards,
-- 
Francis Galiegue, fgaliegue at gmail.com, https://github.com/fge
JSON Schema in Java: http://json-schema-validator.herokuapp.com
Parsers in pure Java: https://github.com/fge/grappa