Improve parse_url_opts documentation (#377)

* Improve parse_url_opts documentation

* fix link

* fmt

Author: alamb

src/parse.rs

@@ -164,9 +164,27 @@ pub fn parse_url(url: &Url) -> Result<(Box<dyn ObjectStore>, Path), super::Error
 
 /// Create an [`ObjectStore`] based on the provided `url` and options
 ///
+/// This method can be used to create an instance of one of the provided
+/// `ObjectStore` implementations based on the URL scheme (see
+/// [`ObjectStoreScheme`] for more details).
+///
+/// For example
+/// * `file:///path/to/my/file` will return a [`LocalFileSystem`] instance
+/// * `s3://bucket/path` will return an [`AmazonS3`] instance if the `aws` feature is enabled.
+///
+/// Arguments:
+/// * `url`: The URL to parse
+/// * `options`: A list of key-value pairs to pass to the [`ObjectStore`] builder.
+///   Note different object stores accept different configuration options, so
+///   the options that are read depends on the `url` value. One common pattern
+///   is to pass configuration information via process variables using
+///   [`std::env::vars`].
+///
 /// Returns
 /// - An [`ObjectStore`] of the corresponding type
 /// - The [`Path`] into the [`ObjectStore`] of the addressed resource
+///
+/// [`AmazonS3`]: https://docs.rs/object_store/0.12.0/object_store/aws/struct.AmazonS3.html
 pub fn parse_url_opts<I, K, V>(
     url: &Url,
     options: I,