chore: Polish docs for Capability (#3635)

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
 ///

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))));
                 }