Skip to content

Commit 5569c6c

Browse files
authored
docs: align Rust crate and API docs (#7969)
* docs: align Rust crate and API docs * docs: regenerate derived service documentation
1 parent 1ca9c4c commit 5569c6c

193 files changed

Lines changed: 1497 additions & 1057 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci_core.yml‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,9 +51,20 @@ jobs:
5151
distribution: zulu
5252
java-version: 25
5353

54+
- name: Add wasm target
55+
run: rustup target add wasm32-unknown-unknown
56+
5457
- name: Cargo doc
5558
working-directory: core
56-
run: cargo doc --lib --no-deps --all-features
59+
env:
60+
RUSTDOCFLAGS: >-
61+
-D rustdoc::broken_intra_doc_links
62+
-D rustdoc::invalid_rust_codeblocks
63+
-D rustdoc::bare_urls
64+
run: |
65+
cargo doc --workspace --lib --no-deps --all-features
66+
cargo doc --package opendal-service-opfs --lib --no-deps --all-features \
67+
--target wasm32-unknown-unknown
5768

5869
check_clippy:
5970
runs-on: ubuntu-latest

‎.github/workflows/docs.yml‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,11 @@ env:
4444
# Check this page for updating: https://docs.rs/crate/opendal/latest/builds
4545
RUST_DOC_TOOLCHAIN: nightly-2026-04-30
4646
# Enable cfg docsrs to make sure docs are built.
47-
RUSTDOCFLAGS: "--cfg docsrs"
47+
RUSTDOCFLAGS: >-
48+
--cfg docsrs
49+
-D rustdoc::broken_intra_doc_links
50+
-D rustdoc::invalid_rust_codeblocks
51+
-D rustdoc::bare_urls
4852

4953
jobs:
5054
build-rust-doc:
@@ -63,6 +67,7 @@ jobs:
6367
- name: Setup Rust Nightly
6468
run: |
6569
rustup toolchain install ${{ env.RUST_DOC_TOOLCHAIN }}
70+
rustup target add wasm32-unknown-unknown --toolchain ${{ env.RUST_DOC_TOOLCHAIN }}
6671

6772
- uses: actions/setup-java@v5
6873
with:
@@ -71,7 +76,12 @@ jobs:
7176

7277
- name: Build OpenDAL doc
7378
working-directory: core
74-
run: cargo +${{ env.RUST_DOC_TOOLCHAIN }} doc --lib --no-deps --all-features
79+
run: |
80+
cargo +${{ env.RUST_DOC_TOOLCHAIN }} doc \
81+
--workspace --lib --no-deps --all-features
82+
cargo +${{ env.RUST_DOC_TOOLCHAIN }} doc \
83+
--package opendal-service-opfs --lib --no-deps --all-features \
84+
--target wasm32-unknown-unknown
7585
env:
7686
LD_LIBRARY_PATH: ${{ env.JAVA_HOME }}/lib/server:${{ env.LD_LIBRARY_PATH }}
7787

‎bindings/java/src/main/java/org/apache/opendal/ServiceConfig.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1583,7 +1583,7 @@ class Hf implements ServiceConfig {
15831583
public final String downloadMode;
15841584
/**
15851585
* <p>Endpoint of the Hugging Face Hub.</p>
1586-
* <p>Default is &quot;https://huggingface.co&quot;.</p>
1586+
* <p>The default is <code>https://huggingface.co</code>.</p>
15871587
*/
15881588
public final String endpoint;
15891589
/**

‎bindings/python/python/opendal/config.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -382,7 +382,7 @@ class HfConfig(TypedDict):
382382
download_mode: NotRequired[str]
383383
"""Download mode. Either `xet` (default) or `http`. When unset, the mode is resolved from the `HF_HUB_DISABLE_XET` environment variable: a non-empty value forces `http`, otherwise it defaults to `xet`. An explicit value here takes precedence. See <https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhubdisablexet>."""
384384
endpoint: NotRequired[str]
385-
"""Endpoint of the Hugging Face Hub. Default is "https://huggingface.co"."""
385+
"""Endpoint of the Hugging Face Hub. The default is `https://huggingface.co`."""
386386
repo_id: NotRequired[str]
387387
"""Repo id of this backend. This is required."""
388388
repo_type: NotRequired[str]

‎core/README.md‎

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,8 @@ Apache OpenDAL™ is an Open Data Access Layer that enables seamless interaction
2020
- **API reference**: [docs.rs/opendal](https://docs.rs/opendal/) (release) | [dev](https://opendal.apache.org/docs/rust/opendal/)
2121
- **Services & configuration**: [opendal.apache.org/services](https://opendal.apache.org/services)
2222
- **Concepts**: [opendal.apache.org/docs/concepts](https://opendal.apache.org/docs/concepts)
23-
- [Upgrade Guide](https://docs.rs/opendal/latest/opendal/docs/upgrade/index.html) | [Release Notes](https://docs.rs/opendal/latest/opendal/docs/changelog/index.html) | [RFCs](https://docs.rs/opendal/latest/opendal/docs/rfcs/index.html)
24-
- [Examples](./examples)
23+
- [Upgrade Guide](https://github.com/apache/opendal/blob/main/core/core/src/docs/upgrade.md) | [Release Notes](https://github.com/apache/opendal/blob/main/CHANGELOG.md) | [RFCs](https://github.com/apache/opendal/tree/main/core/core/src/docs/rfcs)
24+
- [Examples](https://github.com/apache/opendal/tree/main/core/examples)
2525

2626
## Installation
2727

@@ -83,21 +83,26 @@ timeout, and concurrency limit are built in:
8383

8484
```rust
8585
use opendal::layers::RetryLayer;
86+
use opendal::services::Memory;
87+
use opendal::{Operator, Result};
8688

87-
let op = op.layer(RetryLayer::new());
89+
fn build_operator() -> Result<Operator> {
90+
let op = Operator::new(Memory::default())?;
91+
Ok(op.layer(RetryLayer::new()))
92+
}
8893
```
8994

9095
See [Going to production](https://opendal.apache.org/docs/core/production) and the
9196
[`layers` module](https://docs.rs/opendal/latest/opendal/layers/index.html).
9297

9398
## Contributing
9499

95-
Check out the [CONTRIBUTING](./CONTRIBUTING.md) guide for building, testing, and
100+
Check out the [CONTRIBUTING](https://github.com/apache/opendal/blob/main/CONTRIBUTING.md) guide for building, testing, and
96101
submitting changes to the core.
97102

98103
## Used by
99104

100-
Check out the [users](./users.md) list for more details on who is using OpenDAL.
105+
Check out the [users](https://github.com/apache/opendal/blob/main/core/users.md) list for more details on who is using OpenDAL.
101106

102107
## Branding
103108

@@ -107,6 +112,6 @@ For more details, see the [Apache Product Name Usage Guide](https://www.apache.o
107112

108113
## License and Trademarks
109114

110-
Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0
115+
Licensed under the Apache License, Version 2.0: <http://www.apache.org/licenses/LICENSE-2.0>
111116

112117
Apache OpenDAL, OpenDAL, and Apache are either registered trademarks or trademarks of the Apache Software Foundation.

‎core/core/Cargo.toml‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,6 @@ services-memory = []
6262

6363
[lib]
6464
bench = false
65-
doctest = false
6665

6766
[dependencies]
6867
# Required dependencies

‎core/core/README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,8 @@ behavior explicitly:
4040

4141
- A service crate exports a builder that implements `opendal_core::Builder`.
4242
Pass the configured builder to `Operator::new`.
43-
- A layer crate exports a type that implements `opendal_core::Layer`. Pass the
44-
configured layer to `Operator::layer`.
43+
- A layer crate exports a type that implements `opendal_core::raw::Layer`. Pass
44+
the configured layer to `Operator::layer`.
4545
- An HTTP transport crate exports an `opendal_core::HttpTransport`
4646
implementation. Wrap it in `HttpTransporter` and place it in the operator's
4747
`OperationContext`.
@@ -54,7 +54,7 @@ cargo add opendal-core opendal-service-s3 opendal-layer-retry
5454
cargo add opendal-http-transport-reqwest
5555
```
5656

57-
```rust
57+
```rust,ignore
5858
use opendal_core::HttpTransporter;
5959
use opendal_core::OperationContext;
6060
use opendal_core::Operator;

‎core/core/src/blocking/delete.rs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ impl Deleter {
4040
///
4141
/// Also see:
4242
///
43-
/// - [`BlockingDeleter::delete_try_iter`]: delete an fallible iterator of paths.
43+
/// - [`Deleter::delete_try_iter`]: delete a fallible iterator of paths.
4444
pub fn delete_iter<I, D>(&mut self, iter: I) -> Result<()>
4545
where
4646
I: IntoIterator<Item = D>,
@@ -53,7 +53,7 @@ impl Deleter {
5353
///
5454
/// Also see:
5555
///
56-
/// - [`BlockingDeleter::delete_iter`]: delete an infallible iterator of paths.
56+
/// - [`Deleter::delete_iter`]: delete an infallible iterator of paths.
5757
pub fn delete_try_iter<I, D>(&mut self, try_iter: I) -> Result<()>
5858
where
5959
I: IntoIterator<Item = Result<D>>,

‎core/core/src/blocking/list.rs‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,8 @@ use crate::*;
2323
/// BlockingLister is designed to list entries at given path in a blocking
2424
/// manner.
2525
///
26-
/// Users can construct Lister by [`blocking::Operator::lister`] or [`blocking::Operator::lister_with`].
26+
/// Users can construct a lister through [`Operator::lister`][crate::blocking::Operator::lister]
27+
/// or [`Operator::lister_options`][crate::blocking::Operator::lister_options].
2728
///
2829
/// - Lister implements `Iterator<Item = Result<Entry>>`.
2930
/// - Lister will return `None` if there is no more entries or error has been returned.

‎core/core/src/blocking/operator.rs‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -282,7 +282,8 @@ impl Operator {
282282
/// | stat file with `/` | `abc/def_file/` | Error `NotFound` |
283283
/// | stat not existing path | `xyz` | Error `NotFound` |
284284
///
285-
/// Refer to [RFC: List Prefix][crate::docs::rfcs::rfc_3243_list_prefix] for more details.
285+
/// Refer to [RFC: List Prefix](https://github.com/apache/opendal/blob/main/core/core/src/docs/rfcs/3243_list_prefix.md)
286+
/// for more details.
286287
///
287288
/// ## Services that not support `create_dir`
288289
///
@@ -334,7 +335,8 @@ impl Operator {
334335
/// | stat file with `/` | `abc/def_file/` | Error `NotFound` |
335336
/// | stat not existing path | `xyz` | Error `NotFound` |
336337
///
337-
/// Refer to [RFC: List Prefix][crate::docs::rfcs::rfc_3243_list_prefix] for more details.
338+
/// Refer to [RFC: List Prefix](https://github.com/apache/opendal/blob/main/core/core/src/docs/rfcs/3243_list_prefix.md)
339+
/// for more details.
338340
///
339341
/// ## Services that not support `create_dir`
340342
///
@@ -711,11 +713,13 @@ impl Operator {
711713
self.handle.block_on(self.op.delete_try_iter(try_iter))
712714
}
713715

714-
/// Create a [`BlockingDeleter`] to continuously remove content from storage.
716+
/// Create a [`blocking::Deleter`] to continuously remove content from
717+
/// storage.
715718
///
716719
/// It leverages batch deletion capabilities provided by storage services for efficient removal.
717720
///
718-
/// Users can have more control over the deletion process by using [`BlockingDeleter`] directly.
721+
/// Use [`blocking::Deleter`] directly for more control over the deletion
722+
/// process.
719723
pub fn deleter(&self) -> Result<blocking::Deleter> {
720724
blocking::Deleter::create(
721725
self.handle.clone(),
@@ -839,7 +843,8 @@ impl Operator {
839843

840844
/// Create a streaming lister for entries whose paths start with the given prefix `path`.
841845
///
842-
/// This function creates a new [`BlockingLister`]; dropping it stops listing.
846+
/// This function creates a new [`blocking::Lister`]; dropping it stops
847+
/// listing.
843848
///
844849
/// # Semantics
845850
///

0 commit comments

Comments
 (0)