According to docstring, text ending with '/~' should be descarded through
the slash. Does not happen:

(substitute-in-file-name "some-string/~$HOME") => some-string/~C:\Users\arthur

However:

(substitute-in-file-name "some-string~/$HOME") => C:\Users\arthur

Which seems to be the promised effect. I guess it was a typo in
the doc string and the code comment, otherwise it is a bug in the
implementation. '//' works as advertised, so I guess it is just a typo in
the doc string.

Furthermore, I find it a bit arcane, or at least unnexpected that I get
a native namestring, instead of Emacs path, since other functions in the
fileo.c return Emacs internal (unix-like) namestrings (thus far I have
tested them).

(substitute-in-file-name "some-string~/$HOME/test") => C:\Users\arthu/test

It can be fixed by wrapping into `expand-file-name', but that might or
might not be desirable (to expand from relative path).

If it is a "feature" to get the native namestring, at least perhaps mention it?