doc: improve FileIO doc (#642)

Signed-off-by: xxchan <[email protected]>

crates/iceberg/src/io/file_io.rs

@@ -32,16 +32,25 @@ use crate::{Error, ErrorKind, Result};
 ///
 /// All path passed to `FileIO` must be absolute path starting with scheme string used to construct `FileIO`.
 /// For example, if you construct `FileIO` with `s3a` scheme, then all path passed to `FileIO` must start with `s3a://`.
+///
+/// Supported storages:
+///
+/// | Storage            | Feature Flag     | Schemes    |
+/// |--------------------|-------------------|------------|
+/// | Local file system  | `storage-fs`      | `file`     |
+/// | Memory             | `storage-memory`  | `memory`   |
+/// | S3                 | `storage-s3`      | `s3`, `s3a`|
+/// | GCS                | `storage-gcs`     | `gs`       |
 #[derive(Clone, Debug)]
 pub struct FileIO {
     inner: Arc<Storage>,
 }
 
 impl FileIO {
-    /// Try to infer file io scheme from path.
+    /// Try to infer file io scheme from path. See [`FileIO`] for supported schemes.
     ///
-    /// If it's a valid url, for example http://example.org, url scheme will be used.
-    /// If it's not a valid url, will try to detect if it's a file path.
+    /// - If it's a valid url, for example `s3://bucket/a`, url scheme will be used, and the rest of the url will be ignored.
+    /// - If it's not a valid url, will try to detect if it's a file path.
     ///
     /// Otherwise will return parsing error.
     pub fn from_path(path: impl AsRef<str>) -> crate::Result<FileIOBuilder> {
@@ -111,6 +120,7 @@ pub struct FileIOBuilder {
 
 impl FileIOBuilder {
     /// Creates a new builder with scheme.
+    /// See [`FileIO`] for supported schemes.
     pub fn new(scheme_str: impl ToString) -> Self {
         Self {
             scheme_str: Some(scheme_str.to_string()),

crates/iceberg/src/io/storage.rs

@@ -69,6 +69,7 @@ impl Storage {
             Scheme::Gcs => Ok(Self::Gcs {
                 config: super::gcs_config_parse(props)?.into(),
             }),
+            // Update doc on [`FileIO`] when adding new schemes.
             _ => Err(Error::new(
                 ErrorKind::FeatureUnsupported,
                 format!("Constructing file io from scheme: {scheme} not supported now",),