Add more documentation to vscode-uri to illustrate usage

[octref]

Previously I had misunderstanding of how to use vscode-uri (#42658),
and recently we have #55891 and #56104.

We need some documentation for Uri.parse and Uri.file to know

• Which one to use?
• What kind of input do they take? For example, on Windows, do Uri.file take /c:/foo, or C:\foo, or /C:\foo? On macOS/Linux, does it take relative paths or only absolute paths?

also for path and fsPath:

• What's the expected output for each in all platforms?
• What's the transformation that happens to the original URI? For example, does drive letter change cases on Windows? Does it normalize slashes to forward slashes?

They should be in JSDocs so it shows up in IntelliSense. Would be great to have them in the vscode-uri readme too.

[jrieken]

It is pretty simply but we should probably do a deep dive, the most documentation can be found on Uri in vscode.d.ts, e.g.

		/**
		 * Create an URI from a file system path. The [scheme](#Uri.scheme)
		 * will be `file`.
		 *
		 * @param path A file system or UNC path.
		 * @return A new Uri instance.
		 */
		static file(path: string): Uri;

		/**
		 * Create an URI from a string. Will throw if the given value is not
		 * valid.
		 *
		 * @param value The string value of an Uri.
		 * @return A new Uri instance.
		 */
		static parse(value: string): Uri;

[jrieken]

And to clarify what the five components are:

/**
 * Uniform Resource Identifier (URI) http://tools.ietf.org/html/rfc3986.
 * This class is a simple parser which creates the basic component paths
 * (http://tools.ietf.org/html/rfc3986#section-3) with minimal validation
 * and encoding.
 *
 *       foo://example.com:8042/over/there?name=ferret#nose
 *       \_/   \______________/\_________/ \_________/ \__/
 *        |           |            |            |        |
 *     scheme     authority       path        query   fragment
 *        |   _____________________|__
 *       / \ /                        \
 *       urn:example:animal:ferret:nose
 *
 *
 */
export default class URI implements UriComponents {