Would anyone object to augmenting the docstring for COMPONENT-RELATIVE-PATHNAME?
Currently it's:
"Extracts the relative pathname applicable for a particular component."
How about something like:
"Returns a pathname for the component argument relative to the pathname of that component's parent."
?
I think the most important thing for the reader to know is what the return value is relative to.
The above isn't ideal, either, because sometimes what this returns is NOT a relative pathname (at least as far as I can tell by reading the source) --- it extracts the value that the system definer sets using :pathname so that the "relative" pathname may well be absolute!
Perhaps:
"Returns a pathname for the component argument intended to be interpreted relative to the pathname of that component's parent. Despite the function's name, the return value may be an absolute pathname, because an absolute pathname may be interpreted relative to another pathname in a degenerate way."
A little long-winded. I'm open to suggestions for improvement.
What about adding a docstring for SPLIT-PATH-STRING, too --- any function that returns three values is worth a docstring!
"Splits the path string S, returning three values: A flag that is either :absolute or :relative, indicating how the rest of the values are to be interpreted. A directory path --- a list of strings, suitable for use with MAKE-PATHNAME when prepended with the flag value. A filename with type extension, possibly NIL in the case of a directory pathname. FORCE-DIRECTORY forces S to be interpreted as a directory pathname (third return value will be NIL, final component of S will be treated as part of the directory path."
By the way, is there any danger that SPLIT-PATH-STRING will be called on a logical pathname string? I don't see anything to keep it from happening. If so, it looks like it will lose badly; split-path-string assumes that the pathname separator is "/".
If you all agree with me, this looks like a job for a launchpad ticket.
Cheers, r