Fix docs.rs and test building docs in CI

.github/workflows/ci.yml

@@ -52,4 +52,15 @@ jobs:
       - uses: actions/checkout@v4
       - uses: dtolnay/rust-toolchain@stable
       - run: cargo build --features ${{ matrix.api_level }} --features ${{ matrix.component }}
-        name: Build minimal features
+        name: Build minimal features
+
+  rustdoc:
+    name: Build Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@nightly
+      - name: Build docs
+        run: cargo doc --all-features --workspace --no-deps
+        env:
+          RUSTDOCFLAGS: "--cfg=docsrs"

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ohos-sys"
-version = "0.2.0-beta4"
+version = "0.2.0"
 edition = "2021"
 description = "Bindings to the native API of OpenHarmony OS"
 license = "Apache-2.0"
@@ -43,8 +43,7 @@ all-components = [
 #! Optionally enable one of the `api-*` features to get access to bindings for newer
 #! OpenHarmony versions.
 
-## Enables bindings for OpenHarmony API-level 10. Enabled by default.
-## Note: this crate is empty if this feature is not selected.
+## No effect. API-10 bindings can't be deselected. The feature exists for internal purposes.
 api-10 = []
 ## Enables bindings for OpenHarmony API-level 11
 api-11 = ["api-10"]

components/drawing/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ohos-drawing-sys"
-version = "0.1.0"
+version = "0.1.1"
 edition = "2021"
 description = "Bindings to the `native_drawing` API of OpenHarmony OS"
 license = "Apache-2.0"
@@ -19,8 +19,7 @@ default = ["api-10"]
 #! Optionally enable one of the `api-*` features to get access to bindings for newer
 #! OpenHarmony versions.
 
-## Enables bindings for OpenHarmony API-level 10. Enabled by default.
-## Note: this crate is empty if this feature is not selected.
+## No effect. API-10 bindings can't be deselected. The feature exists for internal purposes.
 api-10 = []
 ## Enables bindings for OpenHarmony API-level 11
 api-11 = ["api-10"]

components/drawing/src/lib.rs

@@ -1,3 +1,21 @@
+//! FFI Bindings for `native_drawing` on OpenHarmony
+//!
+//! The native drawing module provides APIs for drawing 2D graphics and text.
+//! The graphics and text drawn by using the APIs cannot be directly displayed on the screen.
+//! To display the drawn graphics and text, you'll need the capabilities provided by the <XComponent> and native window module.
+//!
+//! Please consult the official documentation for more details: [English docs], [Chinese docs]
+//!
+//! [English docs]: https://docs.openharmony.cn/pages/v5.0/en/application-dev/graphics/drawing-guidelines.md
+//! [Chinese docs]: https://docs.openharmony.cn/pages/v5.0/zh-cn/application-dev/graphics/drawing-guidelines.md
+//!
+//! ## Feature flags
+#![cfg_attr(
+    feature = "document-features",
+    cfg_attr(doc, doc = ::document_features::document_features!())
+)]
+#![cfg_attr(docsrs, feature(doc_cfg))]
+
 #[link(name = "native_drawing")]
 extern "C" {}
 
@@ -13,51 +31,75 @@ pub mod text_typography;
 pub mod types;
 
 #[cfg(feature = "api-11")]
+#[cfg_attr(docsrs, doc(cfg(feature = "api-11")))]
 pub mod color_filter;
 #[cfg(feature = "api-11")]
+#[cfg_attr(docsrs, doc(cfg(feature = "api-11")))]
 pub mod filter;
 #[cfg(feature = "api-11")]
+#[cfg_attr(docsrs, doc(cfg(feature = "api-11")))]
 pub mod font;
 #[cfg(feature = "api-11")]
+#[cfg_attr(docsrs, doc(cfg(feature = "api-11")))]
 pub mod mask_filter;
 #[cfg(feature = "api-11")]
+#[cfg_attr(docsrs, doc(cfg(feature = "api-11")))]
 pub mod matrix;
 #[cfg(feature = "api-11")]
+#[cfg_attr(docsrs, doc(cfg(feature = "api-11")))]
 pub mod point;
 #[cfg(feature = "api-11")]
+#[cfg_attr(docsrs, doc(cfg(feature = "api-11")))]
 pub mod rect;
 #[cfg(feature = "api-11")]
+#[cfg_attr(docsrs, doc(cfg(feature = "api-11")))]
 pub mod register_font;
 #[cfg(feature = "api-11")]
+#[cfg_attr(docsrs, doc(cfg(feature = "api-11")))]
 pub mod round_rect;
 #[cfg(feature = "api-11")]
+#[cfg_attr(docsrs, doc(cfg(feature = "api-11")))]
 pub mod shader_effect;
 #[cfg(feature = "api-11")]
+#[cfg_attr(docsrs, doc(cfg(feature = "api-11")))]
 pub mod text_blob;
 #[cfg(feature = "api-11")]
+#[cfg_attr(docsrs, doc(cfg(feature = "api-11")))]
 pub mod typeface;
 
 #[cfg(feature = "api-12")]
+#[cfg_attr(docsrs, doc(cfg(feature = "api-12")))]
 pub mod color_space;
 #[cfg(feature = "api-12")]
+#[cfg_attr(docsrs, doc(cfg(feature = "api-12")))]
 pub mod error_code;
 #[cfg(feature = "api-12")]
+#[cfg_attr(docsrs, doc(cfg(feature = "api-12")))]
 pub mod font_mgr;
 #[cfg(feature = "api-12")]
+#[cfg_attr(docsrs, doc(cfg(feature = "api-12")))]
 pub mod gpu_context;
 #[cfg(feature = "api-12")]
+#[cfg_attr(docsrs, doc(cfg(feature = "api-12")))]
 pub mod image;
 #[cfg(feature = "api-12")]
+#[cfg_attr(docsrs, doc(cfg(feature = "api-12")))]
 pub mod image_filter;
 #[cfg(feature = "api-12")]
+#[cfg_attr(docsrs, doc(cfg(feature = "api-12")))]
 pub mod memory_stream;
 #[cfg(feature = "api-12")]
+#[cfg_attr(docsrs, doc(cfg(feature = "api-12")))]
 pub mod path_effect;
 #[cfg(feature = "api-12")]
+#[cfg_attr(docsrs, doc(cfg(feature = "api-12")))]
 pub mod pixel_map;
 #[cfg(feature = "api-12")]
+#[cfg_attr(docsrs, doc(cfg(feature = "api-12")))]
 pub mod sampling_options;
 #[cfg(feature = "api-12")]
+#[cfg_attr(docsrs, doc(cfg(feature = "api-12")))]
 pub mod shadow_layer;
 #[cfg(feature = "api-12")]
+#[cfg_attr(docsrs, doc(cfg(feature = "api-12")))]
 pub mod surface;

src/lib.rs

@@ -12,7 +12,8 @@
     feature = "document-features",
     cfg_attr(doc, doc = ::document_features::document_features!())
 )]
-#[cfg_attr(docsrs, feature(doc_cfg))]
+#![cfg_attr(docsrs, feature(doc_cfg))]
+
 #[cfg(feature = "drawing")]
 #[cfg_attr(docsrs, doc(cfg(feature = "drawing")))]
 pub mod drawing {

src/native_buffer.rs

@@ -1,3 +1,16 @@
+//! Native Buffer bindings
+//!
+//! The native buffer module provides APIs that you can use to apply for, use, and release the
+//! shared memory, and query memory properties.
+//! The following scenario is common for native buffer development:
+//! Use the native buffer APIs to create an OH_NativeBuffer instance, obtain memory properties,
+//! and map the corresponding ION memory to the process address space.
+//!
+//! Source:
+//!
+//! [English Documentation](https://docs.openharmony.cn/pages/v5.0/en/application-dev/graphics/native-buffer-guidelines.md)
+//! [Chinese Documentation](https://docs.openharmony.cn/pages/v5.0/en/application-dev/graphics/native-buffer-guidelines.md)
+
 #[link(name = "native_buffer")]
 extern "C" {}
 

src/native_window.rs

@@ -1,3 +1,17 @@
+//! Native Window bindings
+//!
+//! The native window module is a local platform-based window that represents the producer of a
+//! graphics queue. It provides APIs for you to request and flush a buffer and configure buffer attributes.
+//! The following scenarios are common for native window development:
+//!  * Request a graphics buffer by using the native window API, write the produced graphics content
+//!    to the buffer, and flush the buffer to the graphics queue.
+//!  *  Request and flush a buffer when adapting to the `eglswapbuffer` interface at the EGL.
+//!
+//! Source:
+//!
+//! [English Documentation](https://docs.openharmony.cn/pages/v5.0/en/application-dev/graphics/native-window-guidelines.md)
+//! [Chinese Documentation](https://docs.openharmony.cn/pages/v5.0/zh-cn/application-dev/graphics/native-window-guidelines.md)
+
 #[link(name = "ace_ndk.z")]
 #[link(name = "native_window")]
 extern "C" {}

src/xcomponent.rs

@@ -1,3 +1,23 @@
+//! Native XComponent bindings
+//!
+//! ## When to Use
+//!
+//! NativeXComponent provides an instance for the <XComponent> at the native layer, which can be
+//! used as a bridge for binding with the <XComponent> at the JS layer. The NDK APIs provided by the
+//! <XComponent> depend on this instance. The provided APIs include those for obtaining a native
+//! window, obtaining the layout or event information of the <XComponent>, registering the lifecycle
+//! callbacks of the <XComponent>, and registering the callbacks for the touch, mouse, and key events
+//! of the <XComponent>. You can use the provided APIs in the following scenarios:
+//!
+//!  * Register the lifecycle and event callbacks of the <XComponent>.
+//!  * Initialize the environment, obtain the current state, and respond to various events via these callbacks.
+//!  * Use the native window and EGL APIs to develop custom drawing content, and apply for and submit buffers to the graphics queue.
+//!
+//! Source:
+//!
+//! [English Documentation](https://docs.openharmony.cn/pages/v5.0/en/application-dev/ui/napi-xcomponent-guidelines.md)
+//! [Chinese Documentation](https://docs.openharmony.cn/pages/v5.0/zh-cn/application-dev/ui/napi-xcomponent-guidelines.md)
+
 #[link(name = "ace_ndk.z")]
 extern "C" {}