(incubator-opendal) branch main updated: chore: Polish docs for Capability (#3635)

[xuanwo]

This is an automated email from the ASF dual-hosted git repository.

xuanwo pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-opendal.git


The following commit(s) were added to refs/heads/main by this push:
     new 79656c047 chore: Polish docs for Capability (#3635)
79656c047 is described below

commit 79656c0476efb162c0d8ab89563bd4c5dae5c6a4
Author: Xuanwo <git...@xuanwo.io>
AuthorDate: Tue Nov 21 03:24:25 2023 +0800

    chore: Polish docs for Capability (#3635)
---
 core/src/types/capability.rs | 20 +++++++++++++++-----
 core/src/types/list.rs       |  1 -
 2 files changed, 15 insertions(+), 6 deletions(-)

diff --git a/core/src/types/capability.rs b/core/src/types/capability.rs
index 4e85f4106..c6f4fc52c 100644
--- a/core/src/types/capability.rs
+++ b/core/src/types/capability.rs
@@ -16,6 +16,7 @@
 // under the License.
 
 use std::fmt::Debug;
+
 /// Capability is used to describe what operations are supported
 /// by current Operator.
 ///
@@ -29,12 +30,21 @@ use std::fmt::Debug;
 ///
 /// # Notes
 ///
-/// Capabilities reflects the native support for operations. It's possible
-/// that some operations are not supported by current Operator, but still
-/// can be used.
+/// Every operator has two kinds of capabilities:
+///
+/// - 
[`OperatorInfo::native_capability`][crate::OperatorInfo::native_capability] 
reflects the native
+///   support for operations.
+/// - [`OperatorInfo::full_capability`][crate::OperatorInfo::full_capability] 
reflects the full support
+///   for operations.
+///
+/// It's possible that some operations are not supported by current Operator, 
but still
+/// can be used. For examples:
+///
+/// - S3 doesn't support `seek` natively, but we implement it via `range` 
header.
+/// - S3 doesn't support blocking API, but `BlockingLayer` makes it possible.
 ///
-/// For examples, we will support `seek` and `next` for all readers
-/// returned by services.
+/// Users can use full_capability to decide what operations can be used and 
use native_capability to
+/// decide if this operation optimized or not.
 ///
 /// # Naming Style
 ///
diff --git a/core/src/types/list.rs b/core/src/types/list.rs
index ce511155a..3611f7c1a 100644
--- a/core/src/types/list.rs
+++ b/core/src/types/list.rs
@@ -99,7 +99,6 @@ impl Stream for Lister {
         match ready!(self.lister.poll_next(cx)) {
             Ok(Some(oe)) => {
                 let (path, metadata) = oe.into_entry().into_parts();
-                // TODO: we can optimize this by checking the provided metakey 
provided by services.
                 if metadata.contains_metakey(self.required_metakey) {
                     return Poll::Ready(Some(Ok(Entry::new(path, metadata))));
                 }