This commit is starting as attempt to add useful context for link functions
in the comments / docstrings, and clean up a few things for better
readability. This is preliminary work for a solution to:
https://github.com/vimwiki/vimwiki/issues/1271
...which is gradually becoming a description of everything that's wrong
with how VimWiki links to files, more or less.
It includes a decision document, which should become a full description
of the problem and steps taken.
This commit _will_ be rewritten.
Bug: #1271
Brennen Bearnes