docs(capi): document setup functions

Cargo.toml

@@ -47,3 +47,7 @@ resolver = "2"
 lto = true
 debug = true
 panic = "abort"
+
+[package.metadata.docs.rs]
+features = ["capi", "sqlite"]
+rustdoc-args = ["-Zunstable-options", "--sort-modules-by-appearance"]

src/capi/internal/mod.rs

@@ -0,0 +1,9 @@
+//! Internal functions visible for tests only
+
+mod key2pho;
+mod path;
+mod utf8;
+
+pub use key2pho::*;
+pub use path::*;
+pub use utf8::*;

src/capi/io.rs

@@ -12,12 +12,9 @@ use std::{
 use tracing::{debug, warn};
 
 use crate::{
-    capi::{
-        public::{
-            ChewingConfigData, IntervalType, CHINESE_MODE, FULLSHAPE_MODE, HALFSHAPE_MODE,
-            MAX_SELKEY, SYMBOL_MODE,
-        },
-        types::{ChewingContext, SelKeys},
+    capi::public::{
+        ChewingConfigData, ChewingContext, IntervalType, SelKeys, CHINESE_MODE, FULLSHAPE_MODE,
+        HALFSHAPE_MODE, MAX_SELKEY, SYMBOL_MODE,
     },
     conversion::{ChewingEngine, Interval, Symbol},
     dictionary::{LayeredDictionary, SystemDictionaryLoader, UserDictionaryLoader},

src/capi/mod.rs

@@ -1,10 +1,147 @@
 #![deny(unsafe_op_in_unsafe_fn)]
 #![allow(unsafe_code)]
 
-pub mod ffi;
-pub mod io;
-pub mod key2pho;
-pub mod path;
-pub mod public;
-pub mod types;
-pub mod utf8;
+mod ffi;
+mod io;
+mod public;
+
+#[doc(hidden)]
+pub mod internal;
+
+/// Initializes chewing context and environment settings
+///
+/// Most of the Chewing IM APIs require a [ChewingContext]. To create a
+/// ChewingContext you must use the [chewing_new] function.
+///
+/// # Examples
+///
+/// Create a chewing context and deletes it after use.
+///
+/// ```c
+/// #include <chewing.h>
+/// int main(int argc, char *argv[])
+/// {
+///     ChewingContext *ctx = chewing_new();
+///
+///     /* do something */
+///
+///     chewing_delete( ctx );
+///
+///     return 0;
+/// }
+/// ```
+///
+/// # Environment variables
+///
+/// * `CHEWING_PATH`
+///     * The CHEWING_PATH environment variable is used to set the search path
+///       of static data used by the Chewing IM. The format of CHEWING_PATH is
+///       the same as PATH, which is multiple paths separated by ‘:’ on POSIX
+///       and Unix-like platforms, or separated by ‘;’ on Windows platform. The
+///       directories in CHEWING_PATH could be read-only.
+/// * `CHEWING_USER_PATH`
+///     * The CHEWING_USER_PATH environment variable is used to specifies the
+///       path where user-defined hash data stores. This path should be writable
+///       by the user, or the Chewing IM will lose the ability to remember the
+///       learned phrases.
+pub mod setup {
+    /// This function exists only for backword compatibility.
+    ///
+    /// The `chewing_Init` function is no-op now. The return value is always 0.
+    pub use super::io::chewing_Init;
+
+    /// Creates a new instance of the Chewing IM.
+    ///
+    /// The return value is a pointer to the new Chewing IM instance.
+    ///
+    /// See also the [chewing_new2], and [chewing_delete] functions.
+    pub use super::io::chewing_new;
+
+    /// Creates a new instance of the Chewing IM.
+    ///
+    /// The `syspath` is the directory path to system dictionary. The `userpath`
+    /// is file path to user dictionary. User shall have enough permission to
+    /// update this file. The logger and loggerdata is logger function and its
+    /// data.
+    ///
+    /// All parameters will be default if set to NULL.
+    ///
+    /// The return value is a pointer to the new Chewing IM instance. See also
+    /// the [chewing_new], [chewing_delete] function.
+    pub use super::io::chewing_new2;
+
+    /// Releases the resources used by the given Chewing IM instance.
+    pub use super::io::chewing_delete;
+
+    /// Sets the selectAreaLen, maxChiSymbolLen and selKey parameter from pcd
+    ///
+    /// The pcd argument is a pointer to a Chewing configuration data structure.
+    /// See also the ChewingConfigData data type.
+    ///
+    /// The return value is 0 on success and -1 on failure.
+    ///
+    /// **Deprecated**, use the chewing_set_* function series to set parameters
+    /// instead.
+    pub use super::io::chewing_Configure;
+
+    /// Resets all settings in the given Chewing IM instance.
+    ///
+    /// The return value is 0 on success and -1 on failure.
+    pub use super::io::chewing_Reset;
+
+    /// Releases the memory allocated by the Chewing IM and returned to the
+    /// caller.
+    ///
+    /// There are functions returning pointers of strings or other data
+    /// structures that are allocated on the heap. These memory must be freed to
+    /// avoid memory leak. To avoid memory allocator mismatch between the
+    /// Chewing IM and the caller, use this function to free the resource.
+    ///
+    /// Do nothing if ptr is NULL.
+    pub use super::io::chewing_free;
+
+    /// Sets the logger function logger.
+    ///
+    /// The logger function is used to provide log inside Chewing IM for
+    /// debugging. The data in chewing_set_logger is passed directly to data in
+    /// logger when logging.
+    ///
+    /// # Examples
+    ///
+    /// The following example shows how to use data:
+    ///
+    /// ```c
+    /// void logger( void *data, int level, const char *fmt, ... )
+    /// {
+    ///     FILE *fd = (FILE *) data;
+    ///     ...
+    /// }
+    ///
+    /// int main()
+    /// {
+    ///     ChewingContext *ctx;
+    ///     FILE *fd;
+    ///     ...
+    ///     chewing_set_logger(ctx, logger, fd);
+    ///     ...
+    /// }
+    /// ```
+    ///
+    /// The level is log level.
+    pub use super::io::chewing_set_logger;
+
+    pub use super::public::ChewingContext;
+
+    pub use super::public::CHEWING_LOG_VERBOSE;
+
+    pub use super::public::CHEWING_LOG_DEBUG;
+
+    pub use super::public::CHEWING_LOG_INFO;
+
+    pub use super::public::CHEWING_LOG_WARN;
+
+    pub use super::public::CHEWING_LOG_ERROR;
+}
+
+pub use io::*;
+pub use public::*;

src/capi/public.rs

@@ -1,29 +1,52 @@
-use std::ffi::c_int;
+use std::{ffi::c_int, iter::Peekable};
 
+use crate::{
+    conversion::{ChewingEngine, Interval},
+    dictionary::DictEntries,
+    editor::{keyboard::AnyKeyboardLayout, syllable::KeyboardLayoutCompat, Editor},
+};
+
+/// Indicates chewing will translate keystrokes to Chinese characters
 pub const CHINESE_MODE: c_int = 1;
+/// Indicates the input mode is translating keystrokes to symbols
 pub const SYMBOL_MODE: c_int = 0;
+/// Indicates chewing will translate latin and puctuation characters to double-with characters
 pub const FULLSHAPE_MODE: c_int = 1;
+/// Indicates chewing will not translate latin and puctuation characters
 pub const HALFSHAPE_MODE: c_int = 0;
+/// Indicates automatic user phrase learning is disabled
 pub const AUTOLEARN_DISABLED: usize = 1;
+/// Indicates automatic user phrase learning is enabled
 pub const AUTOLEARN_ENABLED: usize = 0;
 
+/// The number of minimum candidates that are selectable via shortcut keys
 pub const MIN_SELKEY: usize = 1;
+/// The number of maximum candidates that are selectable via shortcut keys
 pub const MAX_SELKEY: usize = 10;
 
+/// Log level
 pub const CHEWING_LOG_VERBOSE: usize = 1;
+/// Log level
 pub const CHEWING_LOG_DEBUG: usize = 2;
+/// Log level
 pub const CHEWING_LOG_INFO: usize = 3;
+/// Log level
 pub const CHEWING_LOG_WARN: usize = 4;
+/// Log level
 pub const CHEWING_LOG_ERROR: usize = 5;
 
 /// Use "asdfjkl789" as selection key
 pub const HSU_SELKEY_TYPE1: usize = 1;
 /// Use "asdfzxcv89" as selection key
 pub const HSU_SELKEY_TYPE2: usize = 2;
 
+/// Configuration for chewing runtime features
+///
 /// Deprecated, use chewing_set_ series of functions to set parameters instead.
+///
 /// cbindgen:rename-all=CamelCase
 #[repr(C)]
+#[deprecated]
 pub struct ChewingConfigData {
     pub cand_per_page: c_int,
     pub max_chi_symbol_len: c_int,
@@ -37,10 +60,50 @@ pub struct ChewingConfigData {
     pub hsu_sel_key_type: c_int,
 }
 
+/// Specifies the interval of a phrase segment in the pre-editng area
 #[repr(C)]
 pub struct IntervalType {
     /// Starting position of certain interval
     pub from: c_int,
     /// Ending position of certain interval (exclusive)
     pub to: c_int,
 }
+
+/// Keyboard layout index
+///
+/// cbindgen:prefix-with-name
+/// cbindgen:enum-trailing-values=[TypeNum]
+#[derive(Clone, Copy, Debug, PartialEq)]
+#[repr(C)]
+pub enum KB {
+    Default,
+    Hsu,
+    Ibm,
+    GinYieh,
+    Et,
+    Et26,
+    Dvorak,
+    DvorakHsu,
+    DachenCp26,
+    HanyuPinyin,
+    ThlPinyin,
+    Mps2Pinyin,
+    Carpalx,
+}
+
+/// Opaque context handle used for chewing APIs
+///
+/// cbindgen:rename-all=None
+pub struct ChewingContext {
+    pub(crate) kb_compat: KeyboardLayoutCompat,
+    pub(crate) keyboard: AnyKeyboardLayout,
+    pub(crate) editor: Editor<ChewingEngine>,
+    pub(crate) kbcompat_iter: Option<Peekable<Box<dyn Iterator<Item = KeyboardLayoutCompat>>>>,
+    pub(crate) cand_iter: Option<Peekable<Box<dyn Iterator<Item = String>>>>,
+    pub(crate) interval_iter: Option<Peekable<Box<dyn Iterator<Item = Interval>>>>,
+    pub(crate) userphrase_iter: Option<Peekable<DictEntries>>,
+    pub(crate) sel_keys: SelKeys,
+}
+
+#[repr(C)]
+pub(crate) struct SelKeys(pub(crate) [c_int; MAX_SELKEY]);

src/capi/types.rs

@@ -1,43 +1 @@
-use std::{ffi::c_int, iter::Peekable};
 
-use crate::{
-    capi::public::MAX_SELKEY,
-    conversion::{ChewingEngine, Interval},
-    dictionary::DictEntries,
-    editor::{keyboard::AnyKeyboardLayout, syllable::KeyboardLayoutCompat, Editor},
-};
-
-/// cbindgen:prefix-with-name
-/// cbindgen:enum-trailing-values=[TypeNum]
-#[derive(Clone, Copy, Debug, PartialEq)]
-#[repr(C)]
-pub enum KB {
-    Default,
-    Hsu,
-    Ibm,
-    GinYieh,
-    Et,
-    Et26,
-    Dvorak,
-    DvorakHsu,
-    DachenCp26,
-    HanyuPinyin,
-    ThlPinyin,
-    Mps2Pinyin,
-    Carpalx,
-}
-
-/// cbindgen:rename-all=None
-pub struct ChewingContext {
-    pub(crate) kb_compat: KeyboardLayoutCompat,
-    pub(crate) keyboard: AnyKeyboardLayout,
-    pub(crate) editor: Editor<ChewingEngine>,
-    pub(crate) kbcompat_iter: Option<Peekable<Box<dyn Iterator<Item = KeyboardLayoutCompat>>>>,
-    pub(crate) cand_iter: Option<Peekable<Box<dyn Iterator<Item = String>>>>,
-    pub(crate) interval_iter: Option<Peekable<Box<dyn Iterator<Item = Interval>>>>,
-    pub(crate) userphrase_iter: Option<Peekable<DictEntries>>,
-    pub(crate) sel_keys: SelKeys,
-}
-
-#[repr(C)]
-pub(crate) struct SelKeys(pub(crate) [c_int; MAX_SELKEY]);

src/lib.rs

@@ -1,7 +1,7 @@
 #![deny(elided_lifetimes_in_paths)]
 #![deny(macro_use_extern_crate)]
 #![deny(missing_abi)]
-// #![warn(missing_debug_implementations)]
+#![warn(missing_debug_implementations)]
 // #![deny(missing_docs)]
 #![warn(noop_method_call)]
 #![warn(single_use_lifetimes)]
@@ -12,7 +12,7 @@
 #![warn(unused_macro_rules)]
 #![warn(unused_qualifications)]
 #![warn(unused_tuple_struct_fields)]
-// #![warn(variant_size_differences)]
+#![warn(variant_size_differences)]
 
 //! TODO: docs
 //!