[#41] Fix broken links in documentation

This found several bugs in rustdoc:

- rust-lang/rust#81979
- rust-lang/rust#81980
- rust-lang/rust#81981

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)

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},

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);
 

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<u8> and return [`YDBResult<Vec<u8>>`][YDBResult]. The return Vec<u8> will either contain
 //! the data fetched from the database or an error.
 //!
@@ -97,7 +97,7 @@ pub type YDBResult<T> = Result<T, YDBError>;
 /// 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<TpToken> 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<S: Into<String>> From<S> 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