doc: update doc in tauri-utils and tauri (#2435)

* Update several documentations in tauri-utils

* Update a few documentation in tauri

* Add change file

* Update macro usage

Author: Ngo Iok Ui (Wu Yu Wei)

.changes/doc-tauri-utils.md

@@ -0,0 +1,5 @@
+---
+"tauri": minor
+---
+
+`tauri::api` no longer re-export items in `tauri-utils`. We already expose necessary items in the root of `tauri`.

core/tauri-codegen/src/lib.rs

@@ -9,7 +9,7 @@ use std::{
   io::BufReader,
   path::{Path, PathBuf},
 };
-pub use tauri_utils::config::Config;
+use tauri_utils::config::Config;
 use thiserror::Error;
 
 mod context;

core/tauri-utils/src/assets.rs

@@ -2,7 +2,8 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
-//! Assets handled by Tauri during compile time and runtime.
+//! The Assets module allows you to read files that have been bundled by tauri
+//! during both compile time and runtime.
 
 #[doc(hidden)]
 pub use phf;

core/tauri-utils/src/config.rs

@@ -198,7 +198,7 @@ impl Default for UpdaterConfig {
 #[derive(PartialEq, Deserialize, Debug, Clone, Default)]
 #[serde(rename_all = "camelCase")]
 pub struct SecurityConfig {
-  /// Content security policy to inject to HTML files with the custom protocol.
+  /// Content security policy to inject to HTML files with `tauri://` and other user-defined custom protocols.
   pub csp: Option<String>,
 }
 
@@ -301,21 +301,30 @@ pub struct CliArg {
   pub index: Option<u64>,
 }
 
-/// The CLI root command definition.
+/// The CLI command definition.
 #[derive(PartialEq, Deserialize, Debug, Clone)]
 #[serde(rename_all = "camelCase")]
-#[allow(missing_docs)] // TODO
 pub struct CliConfig {
+  /// Command description which will be shown on the help information.
   pub description: Option<String>,
+  /// Command long description which will be shown on the help information.
   pub long_description: Option<String>,
+  /// Adds additional help information to be displayed in addition to auto-generated help.
+  /// This information is displayed before the auto-generated help information.
+  /// This is often used for header information.
   pub before_help: Option<String>,
+  /// Adds additional help information to be displayed in addition to auto-generated help.
+  /// This information is displayed after the auto-generated help information.
+  /// This is often used to describe how to use the arguments, or caveats to be noted.
   pub after_help: Option<String>,
+  /// List of arguments for the command
   pub args: Option<Vec<CliArg>>,
+  /// List of subcommands of this command
   pub subcommands: Option<HashMap<String, CliConfig>>,
 }
 
 impl CliConfig {
-  /// List of args for the command
+  /// List of arguments for the command
   pub fn args(&self) -> Option<&Vec<CliArg>> {
     self.args.as_ref()
   }
@@ -426,10 +435,10 @@ pub enum AppUrl {
 #[derive(PartialEq, Deserialize, Debug)]
 #[serde(rename_all = "camelCase")]
 pub struct BuildConfig {
-  /// the devPath config.
+  /// Directory path or URL to use on development. Default to `http://localhost:8080`.
   #[serde(default = "default_dev_path")]
   pub dev_path: AppUrl,
-  /// the dist config.
+  /// Distribution directory to use in release build. Default to `../dist`.
   #[serde(default = "default_dist_path")]
   pub dist_dir: AppUrl,
   /// Whether we should inject the Tauri API on `window.__TAURI__` or not.
@@ -467,7 +476,7 @@ pub struct PackageConfig {
   pub version: Option<String>,
 }
 
-/// The tauri.conf.json mapper.
+/// The config type mapped to `tauri.conf.json`.
 #[derive(Debug, Default, PartialEq, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct Config {

core/tauri-utils/src/html.rs

@@ -2,6 +2,8 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+//! The module to process HTML in Tauri.
+
 use html5ever::{interface::QualName, namespace_url, ns, LocalName};
 use kuchiki::{Attribute, ExpandedName, NodeRef};
 

core/tauri-utils/src/lib.rs

@@ -5,21 +5,17 @@
 //! Tauri utility helpers
 #![warn(missing_docs, rust_2018_idioms)]
 
-/// The Assets module allows you to read files that have been bundled by tauri
 pub mod assets;
-/// Tauri config definition.
 pub mod config;
-/// Tauri HTML processing.
 pub mod html;
-/// Platform helpers
 pub mod platform;
 
-/// `App` package information.
+/// `tauri::App` package information.
 #[derive(Debug, Clone)]
 pub struct PackageInfo {
-  /// App name.
+  /// App name
   pub name: String,
-  /// App version.
+  /// App version
   pub version: String,
 }
 
@@ -31,10 +27,10 @@ impl PackageInfo {
   }
 }
 
-/// Result type alias using the crate's error type.
+/// The result type of `tauri-utils`.
 pub type Result<T> = std::result::Result<T, Error>;
 
-/// The error types.
+/// The error type of `tauri-utils`.
 #[derive(Debug, thiserror::Error)]
 #[non_exhaustive]
 pub enum Error {
@@ -47,7 +43,7 @@ pub enum Error {
   /// Target triple environment error
   #[error("Unable to determine target-environment")]
   Environment,
-  /// Tried to get resource on an unsupported platform.
+  /// Tried to get resource on an unsupported platform
   #[error("Unsupported platform for reading resources")]
   UnsupportedPlatform,
   /// Get parent process error
@@ -59,7 +55,7 @@ pub enum Error {
   /// Get child process error
   #[error("Could not get child process")]
   ChildProcess,
-  /// IO error.
+  /// IO error
   #[error("{0}")]
   Io(#[from] std::io::Error),
 }

core/tauri-utils/src/platform.rs

@@ -2,6 +2,8 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+//! Platform helper functions.
+
 use std::{
   env,
   path::{PathBuf, MAIN_SEPARATOR},

core/tauri/src/api/mod.rs

@@ -26,9 +26,6 @@ pub mod shell;
 /// The semver API.
 pub mod version;
 
-/// The Tauri config definition.
-pub use tauri_utils::config;
-
 /// The CLI args interface.
 #[cfg(feature = "cli")]
 #[cfg_attr(doc_cfg, doc(cfg(feature = "cli")))]
@@ -42,6 +39,7 @@ pub use clap;
 #[cfg(notification_all)]
 pub mod notification;
 
+#[doc(hidden)]
 pub use tauri_utils::*;
 
 mod error;

core/tauri/src/lib.rs

@@ -11,7 +11,6 @@
 //! The following are a list of Cargo features that can be enabled or disabled:
 //!
 //! - **wry** *(enabled by default)*: Enables the [wry](https://github.com/tauri-apps/wry) runtime. Only disable it if you want a custom runtime.
-//! - **menu**: Enables application menus support.
 //! - **reqwest-client**: Uses `reqwest` as HTTP client on the `http` APIs. Improves performance, but increases the bundle size.
 //! - **cli**: Enables usage of `clap` for CLI argument parsing. Enabled by default if the `cli` config is defined on the `tauri.conf.json` file.
 //! - **system-tray**: Enables application system tray API. Enabled by default if the `systemTray` config is defined on the `tauri.conf.json` file.
@@ -72,10 +71,6 @@ pub use runtime::{menu::NativeImage, ActivationPolicy};
 
 pub use {
   self::api::assets::Assets,
-  self::api::{
-    config::{Config, WindowUrl},
-    PackageInfo,
-  },
   self::app::{App, AppHandle, Builder, CloseRequestApi, Event, GlobalWindowEvent, PathResolver},
   self::hooks::{
     Invoke, InvokeError, InvokeHandler, InvokeMessage, InvokeResolver, InvokeResponse, OnPageLoad,
@@ -107,6 +102,11 @@ pub use {
   self::window::menu::MenuEvent,
 };
 
+pub use tauri_utils::{
+  config::{Config, WindowUrl},
+  PackageInfo,
+};
+
 /// Reads the config file at compile time and generates a [`Context`] based on its content.
 ///
 /// The default config file path is a `tauri.conf.json` file inside the Cargo manifest directory of