path/filepath: improve `Rel`'s documentation

[miekg]

Go version

1.25.2

Output of go env in your module/workspace:

not relevant

What did you do?

godoc filepath.Rel

What did you see happen?

it shows:

func Rel(basepath, targpath string) (string, error)
    Rel returns a relative path that is lexically equivalent to targpath when
    joined to basepath with an intervening separator. That is, Join(basepath,
    Rel(basepath, targpath)) is equivalent to targpath itself. On success,
    the returned path will always be relative to basepath, even if basepath and
    targpath share no elements. An error is returned if targpath can't be made
    relative to basepath or if knowing the current working directory would be
    necessary to compute it. Rel calls Clean on the result.

What did you expect to see?

As a non-native English speaker, I have a very hard time parsing this text. I (mostly) need this function to figure out if targpath sits below basepath, but whenever I reach for it, I'm stumped every time.

I'm not sure how a better text would look like though. The words 'lexically' and 'intervening seperator' in the first sentence don't help though.

[seankhliao]

They are important words though, as they point out that the processing is only based on the names and not on real filepaths.

[matttproud]

I don't want stir the pot in an unproductive way; I encouraged @miekg to file the issue as I found — as a native speaker — the documentation to be a bit too dense to process. I've played around with it a little and came up with some reformulations that are a little easier for my eyes:

Before:

// Rel returns a relative path that is lexically equivalent to targpath when
// joined to basepath with an intervening separator. That is,
// [Join](basepath, Rel(basepath, targpath)) is equivalent to targpath itself.
// On success, the returned path will always be relative to basepath,
// even if basepath and targpath share no elements.
// An error is returned if targpath can't be made relative to basepath or if
// knowing the current working directory would be necessary to compute it.
// Rel calls [Clean] on the result.
func Rel(basepath, targpath string) (string, error)

After:

// Rel returns a relative path that is lexically equivalent to targPath when
// joined to basePath with an intervening separator. That is,
// Join(basePath, Rel(basePath, targPath)) is equivalent to targPath itself
//
// The returned path will always be relative to basePath, even if basePath and
// targPath share no elements.  Rel calls [Clean] on the result.
//
// An error is returned if targPath can't be made relative to basePath
// or if knowing the current working directory would be necessary to compute it.
func Rel(basePath, targPath string) (string, error)

Chief differences:

• Adjusting the input parameter names to be camel case (convention); this helps them stick out better in the prose as identifiers instead of just text.
• Using paragraph breaks, which helps separate logical topics in the documentation.
• "On success, " is dropped: it doesn't communicate a lot of information, and documenting the success case expressly with "success" is not super conventional in standard library documentation.
• Using native linking to filepath.Clean
• Discussion of the filepath.Clean call is moved away from the error case discussion and to the supplemental information paragraph.

I'm not suggesting that this formulation would have helped 100% in this case, but I find the information significantly more accessible in this reformulated version such that from a cognitive load perspective, more bandwidth is free to potentially answer the question that was posed in one's own head.

[Merovius]

Rel returns a relative path that is lexically equivalent to targPath when joined to basePath with an intervening separator.

I would suggest s/joined/appended/, to make the order of arguments clear. AIUI that is the main confusion @miekg experiences.

[miekg]

The suggested text indeed feels better.

The included example for filepath.Rel could/should probably show how to determine if something is a subdir or not, 'cause if I'm not mistaken you must check the result from Rel for "..", which is a massive (under documented) foot gun

[Jorropo]

@matttproud it's hard to objectively judge documentation but I agree your text is much more readable if only just because of the paragraph breaks.

Would you consider sending a CL ?

[matttproud]

Happily. I can do that in a couple of days. I will use the sketch I described above.

[gabyhelp]

Related Issues

• os: Readlink docs should mention behavior for relative paths #57766 (closed)

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[matttproud]

https://go-review.googlesource.com/c/go/+/712440

[gopherbot]

Change https://go.dev/cl/712440 mentions this issue: filepath: improve func Rel's API documentation