-/* Concatenate two pathname components, DIR and BASE, in newly-allocated
- storage and return the result. Return 0 if out of memory. Add a slash
- between DIR and BASE in the result if neither would contribute one.
- If each would contribute at least one, elide one from the end of DIR.
- Otherwise, simply concatenate DIR and BASE. In any case, if
- BASE_IN_RESULT is non-NULL, set *BASE_IN_RESULT to point to the copy of
- BASE in the returned concatenation. */
+/* Concatenate two pathname components, DIR and ABASE, in
+ newly-allocated storage and return the result.
+ The resulting file name F is such that the commands "ls F" and "(cd
+ DIR; ls BASE)" refer to the same file, where BASE is ABASE with any
+ file system prefixes and leading separators removed.
+ Arrange for a directory separator if necessary between DIR and BASE
+ in the result, removing any redundant separators.
+ In any case, if BASE_IN_RESULT is non-NULL, set
+ *BASE_IN_RESULT to point to the copy of ABASE in the returned
+ concatenation. However, if ABASE begins with more than one slash,
+ set *BASE_IN_RESULT to point to the sole corresponding slash that
+ is copied into the result buffer.
+
+ Report an error if memory is exhausted. */