Improve docstring ReST markup in path.py

# This Pull Request

I basically just wanted to add a bit of markup, to semantically enrich the docs generated by Sphinx.  

I tried not to move anything around, although I believe I was forced to pull a switcheroo when I marked a paragraph using `.. warning::`.  It did already say “Warning”, and it was about potential data loss, so I felt it was worth marking up.  However, the function’s one-line synopsis came after the warning, so I put it first.  Hopefully, no one will get hurt. :)

----

# Unrelated to this Pull Request

I can’t believe that I **just** discovered this module!  It’s fantastic.  Thank you, @jaraco! 

(And thank you “Mikhail Gusarov”, mentioned in the copyright header of `path.py`. Was he the creator?  Has he moved on from the project?)