From d604501ab119ffb537f446ae2c111c04868e5d2c Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Wed, 10 Feb 2021 20:16:14 -0500 Subject: [PATCH] [#41] Fix broken links in documentation This found several bugs in rustdoc: - https://github.com/rust-lang/rust/issues/81979 - https://github.com/rust-lang/rust/issues/81980 - https://github.com/rust-lang/rust/issues/81981 --- src/context_api/mod.rs | 7 +---- src/lib.rs | 56 ++++++++++++++++++--------------------- src/simple_api/call_in.rs | 8 +++--- src/simple_api/mod.rs | 12 ++++----- 4 files changed, 37 insertions(+), 46 deletions(-) diff --git a/src/context_api/mod.rs b/src/context_api/mod.rs index e21716b..10da4e7 100644 --- a/src/context_api/mod.rs +++ b/src/context_api/mod.rs @@ -347,14 +347,12 @@ impl Context { /// ``` /// /// # See Also - /// - [`simple_api::tp_st`](super::simple_api::tp_st()) /// - [More details about the underlying FFI call][C documentation] /// - [Transaction Processing in YottaDB](https://docs.yottadb.com/MultiLangProgGuide/MultiLangProgGuide.html#transaction-processing) /// - [Threads and Transaction Processing][threads and transactions] /// /// [`$zmaxtptime`]: https://docs.yottadb.com/MultiLangProgGuide/MultiLangProgGuide.html#zmaxtptime - /// [`TransactionStatus`]: super::simple_api::TransactionStatus - /// [intrinsics]: crate::simple_api#intrinsic-variables + /// [intrinsics]: crate#intrinsic-variables /// [threads and transactions]: https://docs.yottadb.com/MultiLangProgGuide/programmingnotes.html#threads-and-transaction-processing /// [C documentation]: https://docs.yottadb.com/MultiLangProgGuide/cprogram.html#ydb-tp-s-ydb-tp-st pub fn tp<'a, F>( @@ -424,7 +422,6 @@ impl Context { /// ``` /// /// # See also - /// - [`simple_api::delete_excl_st`](super::simple_api::delete_excl_st()) /// - The [Simple API documentation](https://docs.yottadb.com/MultiLangProgGuide/cprogram.html#ydb-delete-excl-s-ydb-delete-excl-st) /// - [Local and global variables](https://docs.yottadb.com/MultiLangProgGuide/MultiLangProgGuide.html#local-and-global-variables) /// - [Instrinsic special variables](https://docs.yottadb.com/MultiLangProgGuide/MultiLangProgGuide.html#intrinsic-special-variables) @@ -590,7 +587,6 @@ impl Context { /// /// - The C [Simple API documentation](https://docs.yottadb.com/MultiLangProgGuide/cprogram.html#ydb-lock-s-ydb-lock-st) /// - [Locks](https://docs.yottadb.com/MultiLangProgGuide/MultiLangProgGuide.html#locks) - /// - [`simple_api::lock_st`](super::simple_api::lock_st()) /// /// [`KeyContext::lock_incr`]: KeyContext::lock_incr() /// [`KeyContext::lock_decr`]: KeyContext::lock_decr() @@ -611,7 +607,6 @@ impl Context { /// - `YDB_ERR_UNKNOWNSYSERR` if `status` is an unrecognized status code /// /// # See also - /// - [`simple_api::message_t`](super::simple_api::message_t()) /// - [`impl Display for YDBError`][`impl Display`], which should meet most use cases for `message_t`. /// - [Function return codes](https://docs.yottadb.com/MultiLangProgGuide/cprogram.html#function-return-codes) /// - [ZMessage codes](https://docs.yottadb.com/MessageRecovery/errormsgref.html#zmessage-codes) diff --git a/src/lib.rs b/src/lib.rs index 830ac0a..40b05f9 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -18,15 +18,14 @@ //! There are two major APIs: //! - [`craw`], the FFI bindings generated directly by bindgen. //! These are not recommended for normal use, -//! but are available in case the `context_api` is missing functionality. -//! - [`context_api`], which is a safe wrapper around the C API which -//! stores the current tptoken and an error buffer -//! so you don't have to keep track of them yourself. -//! The reason this metadata is necessary is because this crate binds to -//! the threaded version of YottaDB, which requires a `tptoken` and `err_buffer`. -//! See [transaction processing] for more details on transactions and `tptoken`s. -//! -//! Most operations are encapsulated in methods in the [KeyContext] struct. +//! but are available in case the Context API is missing functionality. +//! - The main Context API, which is a safe wrapper around the C API which +//! stores the current tptoken and an error buffer so you don't have to keep track of them yourself. +//! The reason this metadata is necessary is because this crate binds to the threaded version of +//! YottaDB, which requires a `tptoken` and `err_buffer`. See [transaction processing] for more +//! details on transactions and `tptoken`s. +//! +//! Most operations are encapsulated in methods in the [`KeyContext`] struct. //! Iteration helpers are available to iterate over values in the database in a variety of ways. //! //! # Examples @@ -47,6 +46,13 @@ //! } //! ``` //! +//! # Intrinsic Variables +//! +//! YottaDB has several intrinsic variables which are documented [online][intrinsics]. +//! To get the value of these variables, call `get_st` on a `Key` with the name of the variable. +//! +//! ## Example +//! //! Get the instrinsic variable [`$tlevel`][tlevel], which gives the current transaction level. //! //! ``` @@ -62,12 +68,7 @@ //! } //! ``` //! -//! # Intrinsic Variables -//! -//! YottaDB has several intrinsic variables which are documented [online][intrinsics]. -//! To get the value of these variables, call `get_st` on a `Key` with the name of the variable. -//! -//! ## Features +//! # Features //! //! Since `yottadb` is a set of bindings to a C library, it uses `bindgen` to generate the bindings. //! There are two ways to do this: @@ -78,14 +79,14 @@ //! even when you don't have admin priviledges to install programs. //! Using a pre-installed version means compile times are much lower. //! -//! ## Signal handling +//! # Signal handling //! //! YottaDB performs its own signal handling in addition to any signal handlers you may have set up. //! Since many functions in C are not async-safe, it defers any action until the next time `ydb_eintr_handler` is called. //! All YDB functions will automatically call `ydb_eintr_handler` if necessary, //! so in most cases this should not affect your application. However, there are some rare cases //! when the handler will not be called: -//! - If you have a tight loop inside a [`tp`] that does not call a YDB function +//! - If you have a tight loop inside a [`Context::tp`] that does not call a YDB function //! //! For example, the following loop will run forever even if sent SIGINT: //! ```no_run @@ -101,7 +102,7 @@ //! # } //! ``` //! -//! To avoid this, call [`eintr_handler`] in the loop: +//! To avoid this, call [`Context::eintr_handler`] in the loop: //! //! ```no_run //! # fn main() -> yottadb::YDBResult<()> { @@ -126,20 +127,14 @@ //! YottaDB does not register any signal handlers until the first time `ydb_init` is called, //! and deregisters its handlers after `ydb_exit`. //! -//! ### See also +//! ## See also //! //! - The [C documentation on signals](https://docs.yottadb.com/MultiLangProgGuide/programmingnotes.html#signals) -//! - [`eintr_handler`] -//! - [`eintr_handler_t`] -//! - [`tp`] -//! -//! [`YDBError`]: simple_api::YDBError -//! [`eintr_handler`]: context_api::Context::eintr_handler() -//! [`eintr_handler_t`]: simple_api::eintr_handler_t() -//! [`tp`]: context_api::Context::tp() +//! - [`Context::eintr_handler`] +//! - [`Context::tp`](crate::Context::tp) +//! //! [YottaDB]: https://yottadb.com/ //! [transaction processing]: https://docs.yottadb.com/MultiLangProgGuide/MultiLangProgGuide.html#transaction-processing -//! [key]: Key //! [intrinsics]: https://docs.yottadb.com/MultiLangProgGuide/MultiLangProgGuide.html#intrinsic-special-variables //! [tlevel]: https://docs.yottadb.com/MultiLangProgGuide/MultiLangProgGuide.html#tlevel #![deny(missing_docs)] @@ -153,14 +148,15 @@ #[allow(unused)] const INTERNAL_DOCS: () = (); -// Public to reduce churn when upgrading versions, but it's recommended to use the top-level re-exports instead. +/// Public to reduce churn when upgrading versions, but it's recommended to use the top-level re-exports instead. #[doc(hidden)] -pub mod context_api; +mod context_api; #[allow(missing_docs)] pub mod craw; mod simple_api; pub use craw::{YDB_ERR_GVUNDEF, YDB_ERR_LVUNDEF}; +#[doc(inline)] // needed because of rust-lang/rust#81890 pub use context_api::*; // glob import so we catch all the iterators pub use simple_api::{ call_in::{CallInDescriptor, CallInTableDescriptor}, diff --git a/src/simple_api/call_in.rs b/src/simple_api/call_in.rs index 3d5f1e1..a5523c4 100644 --- a/src/simple_api/call_in.rs +++ b/src/simple_api/call_in.rs @@ -21,14 +21,14 @@ use std::ffi::{CString, CStr}; use crate::craw::ci_name_descriptor; use super::{resize_call, YDBResult, TpToken}; -/// The descriptor for a call-in table opened with [`ci_tab_open_t`]. +/// The descriptor for a call-in table opened with [`ci_tab_open`]. /// /// `CallInTableDescriptor::default()` returns a table which, -/// when called with [`ci_tab_switch_t`], uses the environment variable `ydb_ci`. +/// when called with [`ci_tab_switch`], uses the environment variable `ydb_ci`. /// This is also the table that is used if `ci_tab_switch_t` is never called. /// -/// [`ci_tab_open_t`]: ci_tab_open_t() -/// [`ci_tab_switch_t`]: ci_tab_switch_t() +/// [`ci_tab_open`]: crate::Context::ci_tab_open +/// [`ci_tab_switch`]: crate::Context::ci_tab_switch #[derive(Copy, Clone, Debug, Default, Eq, PartialEq)] pub struct CallInTableDescriptor(usize); diff --git a/src/simple_api/mod.rs b/src/simple_api/mod.rs index 6369b84..0c5c1a8 100644 --- a/src/simple_api/mod.rs +++ b/src/simple_api/mod.rs @@ -14,7 +14,7 @@ //! //! The API is not particularly friendly, but it exposes only safe code. //! -//! Most operations are encapsulated in methods on the [`Key`][key] struct, and generally +//! Most operations are encapsulated in methods on the [`Key`] struct, and generally //! consume a Vec and return [`YDBResult>`][YDBResult]. The return Vec will either contain //! the data fetched from the database or an error. //! @@ -97,7 +97,7 @@ pub type YDBResult = Result; /// A transaction processing token, used by yottadb to ensure ACID properties. /// /// The only valid values for a TpToken are the default (`TpToken::default()`) -/// or a token passed in from [`tp_st`](tp_st()). +/// or a token passed in from [`Context::tp`](crate::Context::tp). /// /// TpTokens can be converted to `u64`, but not vice-versa. #[derive(Copy, Clone, Hash, Eq, PartialEq)] @@ -147,7 +147,7 @@ impl From for u64 { /// The type of data available at the current node. /// /// # See also -/// - [`Key::data_st()`] +/// - [`KeyContext::data()`](crate::KeyContext::data) #[derive(Debug, Clone, Eq, PartialEq, Hash)] pub enum DataReturn { /// There is no data present, either here or lower in the tree. @@ -163,7 +163,7 @@ pub enum DataReturn { /// The type of deletion that should be carried out. /// /// # See also -/// - [`Key::delete_st()`] +/// - [`KeyContext::delete_st()`](crate::KeyContext::delete) #[derive(Debug, Clone, Hash, Eq, PartialEq)] pub enum DeleteType { /// Delete only this node. @@ -817,9 +817,9 @@ impl> From for Key { } } -/// The status returned from a callback passed to [`tp_st`] +/// The status returned from a callback passed to [`Context::tp`] /// -/// [`tp_st`]: tp_st() +/// [`Context::tp`]: crate::Context::tp #[derive(Debug, Copy, Clone)] pub enum TransactionStatus { /// Complete the transaction and commit all changes