Fix rustdoc lints (#1373)

At some point we got like a zillion errors in doc-link generation and I
finally had it enough that I wanted them all fixed. This does not
necessarily mean all the docs are good or correctly linked, just that
the lints are silent.

cargo-pgrx/src/command/install.rs

@@ -25,7 +25,7 @@ use std::process::Stdio;
 use std::sync::{Arc, Mutex};
 
 /// Type used for memoizing expensive to calculate values.
-/// Arc<Mutex> is needed to get around compiler safety checks.
+/// `Arc<Mutex>` is needed to get around compiler safety checks.
 type MemoizeKeyValue = Arc<Mutex<HashMap<PathBuf, String>>>;
 
 /// Install the extension from the current crate to the Postgres specified by whatever `pg_config` is currently on your $PATH

pgrx-pg-config/src/cargo.rs

@@ -24,7 +24,7 @@ pub trait PgrxManifestExt {
 
     /// Resolved string for target library name, either its lib.name,
     /// or package name with hyphens replaced with underscore.
-    /// https://doc.rust-lang.org/cargo/reference/cargo-targets.html#the-name-field
+    /// <https://doc.rust-lang.org/cargo/reference/cargo-targets.html#the-name-field>
     fn lib_name(&self) -> eyre::Result<String>;
 
     /// Resolved string for target artifact name, used for matching on

pgrx-pg-sys/src/port.rs

@@ -24,7 +24,7 @@ pub const MaxTransactionId: super::TransactionId = 0xFFFF_FFFF as super::Transac
 ///
 /// # Safety
 ///
-/// This function cannot determine if the `tuple` argument is really a non-null pointer to a [`HeapTuple`].
+/// This function cannot determine if the `tuple` argument is really a non-null pointer to a [`pg_sys::HeapTuple`].
 #[inline(always)]
 pub unsafe fn GETSTRUCT(tuple: crate::HeapTuple) -> *mut std::os::raw::c_char {
     // #define GETSTRUCT(TUP) ((char *) ((TUP)->t_data) + (TUP)->t_data->t_hoff)
@@ -72,6 +72,8 @@ pub const unsafe fn MAXALIGN(len: usize) -> usize {
 ///
 /// This function will panic if `pointer` is null, if it's not properly aligned, or if the memory
 /// it points to doesn't have a prefix that looks like a memory context pointer
+///
+/// [`palloc`]: crate::palloc
 #[allow(non_snake_case)]
 #[cfg(any(feature = "pg12", feature = "pg13", feature = "pg14", feature = "pg15"))]
 pub unsafe fn GetMemoryChunkContext(pointer: *mut std::os::raw::c_void) -> pg_sys::MemoryContext {
@@ -108,7 +110,7 @@ pub unsafe fn GetMemoryChunkContext(pointer: *mut std::os::raw::c_void) -> pg_sy
 /// # Safety
 ///
 /// The caller must only attempt this on a pointer to a Node.
-/// This may clarify if the pointee is correctly-initialized [`MemoryContextData`].
+/// This may clarify if the pointee is correctly-initialized [`pg_sys::MemoryContextData`].
 ///
 /// # Implementation Note
 ///
@@ -208,18 +210,20 @@ pub unsafe fn BufferIsLocal(buffer: crate::Buffer) -> bool {
     buffer < 0
 }
 
-/// Retrieve the "user data" of the specified [`HeapTuple`] as a specific type. Typically this
+/// Retrieve the "user data" of the specified [`pg_sys::HeapTuple`] as a specific type. Typically this
 /// will be a struct that represents a Postgres system catalog, such as [`FormData_pg_class`].
 ///
 /// # Returns
 ///
-/// A pointer to the [`HeapTuple`]'s "user data", cast as a mutable pointer to `T`.  If the
+/// A pointer to the [`pg_sys::HeapTuple`]'s "user data", cast as a mutable pointer to `T`.  If the
 /// specified `htup` pointer is null, the null pointer is returned.
 ///
 /// # Safety
 ///
-/// This function cannot verify that the specified `htup` points to a valid [`HeapTuple`] nor
+/// This function cannot verify that the specified `htup` points to a valid [`pg_sys::HeapTuple`] nor
 /// that if it does, that its bytes are bitwise compatible with `T`.
+///
+/// [`FormData_pg_class`]: crate::FormData_pg_class
 #[inline]
 pub unsafe fn heap_tuple_get_struct<T>(htup: super::HeapTuple) -> *mut T {
     if htup.is_null() {

pgrx-pg-sys/src/submodules/elog.rs

@@ -98,7 +98,7 @@ impl From<i32> for PgLogLevel {
 
 /// Log to Postgres' `debug5` log level.
 ///
-/// This macro accepts arguments like the [`println`](std::println) and [`format`](std::format) macros.
+/// This macro accepts arguments like the [`println`] and [`format`] macros.
 /// See [`fmt`](std::fmt) for information about options.
 ///
 /// The output these logs goes to the PostgreSQL log file at `DEBUG5` level, depending on how the
@@ -115,7 +115,7 @@ macro_rules! debug5 {
 
 /// Log to Postgres' `debug4` log level.
 ///
-/// This macro accepts arguments like the [`println`](std::println) and [`format`](std::format) macros.
+/// This macro accepts arguments like the [`println`] and [`format`] macros.
 /// See [`fmt`](std::fmt) for information about options.
 ///
 /// The output these logs goes to the PostgreSQL log file at `DEBUG4` level, depending on how the
@@ -132,7 +132,7 @@ macro_rules! debug4 {
 
 /// Log to Postgres' `debug3` log level.
 ///
-/// This macro accepts arguments like the [`println`](std::println) and [`format`](std::format) macros.
+/// This macro accepts arguments like the [`println`] and [`format`] macros.
 /// See [`fmt`](std::fmt) for information about options.
 ///
 /// The output these logs goes to the PostgreSQL log file at `DEBUG3` level, depending on how the
@@ -149,7 +149,7 @@ macro_rules! debug3 {
 
 /// Log to Postgres' `debug2` log level.
 ///
-/// This macro accepts arguments like the [`println`](std::println) and [`format`](std::format) macros.
+/// This macro accepts arguments like the [`println`] and [`format`] macros.
 /// See [`fmt`](std::fmt) for information about options.
 ///
 /// The output these logs goes to the PostgreSQL log file at `DEBUG2` level, depending on how the
@@ -166,7 +166,7 @@ macro_rules! debug2 {
 
 /// Log to Postgres' `debug1` log level.
 ///
-/// This macro accepts arguments like the [`println`](std::println) and [`format`](std::format) macros.
+/// This macro accepts arguments like the [`println`] and [`format`] macros.
 /// See [`fmt`](std::fmt) for information about options.
 ///
 /// The output these logs goes to the PostgreSQL log file at `DEBUG1` level, depending on how the
@@ -183,7 +183,7 @@ macro_rules! debug1 {
 
 /// Log to Postgres' `log` log level.
 ///
-/// This macro accepts arguments like the [`println`](std::println) and [`format`](std::format) macros.
+/// This macro accepts arguments like the [`println`] and [`format`] macros.
 /// See [`fmt`](std::fmt) for information about options.
 ///
 /// The output these logs goes to the PostgreSQL log file at `LOG` level, depending on how the
@@ -200,7 +200,7 @@ macro_rules! log {
 
 /// Log to Postgres' `info` log level.
 ///
-/// This macro accepts arguments like the [`println`](std::println) and [`format`](std::format) macros.
+/// This macro accepts arguments like the [`println`] and [`format`] macros.
 /// See [`fmt`](std::fmt) for information about options.
 #[macro_export]
 macro_rules! info {
@@ -214,7 +214,7 @@ macro_rules! info {
 
 /// Log to Postgres' `notice` log level.
 ///
-/// This macro accepts arguments like the [`println`](std::println) and [`format`](std::format) macros.
+/// This macro accepts arguments like the [`println`] and [`format`] macros.
 /// See [`fmt`](std::fmt) for information about options.
 #[macro_export]
 macro_rules! notice {
@@ -228,7 +228,7 @@ macro_rules! notice {
 
 /// Log to Postgres' `warning` log level.
 ///
-/// This macro accepts arguments like the [`println`](std::println) and [`format`](std::format) macros.
+/// This macro accepts arguments like the [`println`] and [`format`] macros.
 /// See [`fmt`](std::fmt) for information about options.
 #[macro_export]
 macro_rules! warning {
@@ -242,7 +242,7 @@ macro_rules! warning {
 
 /// Log to Postgres' `error` log level.  This will abort the current Postgres transaction.
 ///
-/// This macro accepts arguments like the [`println`](std::println) and [`format`](std::format) macros.
+/// This macro accepts arguments like the [`println`] and [`format`] macros.
 /// See [`fmt`](std::fmt) for information about options.
 #[macro_export]
 macro_rules! error {
@@ -257,7 +257,7 @@ macro_rules! error {
 
 /// Log to Postgres' `fatal` log level.  This will abort the current Postgres backend connection process.
 ///
-/// This macro accepts arguments like the [`println`](std::println) and [`format`](std::format) macros.
+/// This macro accepts arguments like the [`println`] and [`format`] macros.
 /// See [`fmt`](std::fmt) for information about options.
 #[allow(non_snake_case)]
 #[macro_export]
@@ -273,7 +273,7 @@ macro_rules! FATAL {
 
 /// Log to Postgres' `panic` log level.  This will cause the entire Postgres cluster to crash.
 ///
-/// This macro accepts arguments like the [`println`](std::println) and [`format`](std::format) macros.
+/// This macro accepts arguments like the [`println`] and [`format`] macros.
 /// See [`fmt`](std::fmt) for information about options.
 #[allow(non_snake_case)]
 #[macro_export]

pgrx-pg-sys/src/submodules/htup.rs

@@ -152,7 +152,7 @@ pub unsafe fn HeapTupleHeaderGetXmin(tup: *const HeapTupleHeaderData) -> Transac
     }
 }
 
-/// How many attributes does the specified [`HeapTupleHeader`] have?
+/// How many attributes does the specified [`HeapTupleHeader`][crate::HeapTupleHeader] have?
 ///
 /// # Safety
 ///
@@ -167,7 +167,7 @@ pub unsafe fn HeapTupleHeaderGetNatts(tup: *const HeapTupleHeaderData) -> u16 {
     }
 }
 
-/// Does the specified [`HeapTuple`] (`tup`) contain nulls?
+/// Does the specified [`HeapTuple`][crate::HeapTuple] contain nulls?
 ///
 /// # Safety
 ///

pgrx-pg-sys/src/submodules/panic.rs

@@ -235,8 +235,8 @@ impl ErrorReportWithLevel {
 }
 
 impl ErrorReport {
-    /// Create a [PgErrorReport] which can be raised via Rust's [std::panic::panic_any()] or as
-    /// a specific Postgres "ereport()` level via [PgErrorReport::report(self, PgLogLevel)]
+    /// Create an [ErrorReport] which can be raised via Rust's [std::panic::panic_any()] or as
+    /// a specific Postgres "ereport()` level via [ErrorReport::report(self, PgLogLevel)]
     ///
     /// Embedded "file:line:col" location information is taken from the caller's location
     #[track_caller]
@@ -251,8 +251,8 @@ impl ErrorReport {
         Self { sqlerrcode, message: message.into(), hint: None, detail: None, location }
     }
 
-    /// Create a [PgErrorReport] which can be raised via Rust's [std::panic::panic_any()] or as
-    /// a specific Postgres "ereport()` level via [PgErrorReport::report(self, PgLogLevel)].
+    /// Create an [ErrorReport] which can be raised via Rust's [std::panic::panic_any()] or as
+    /// a specific Postgres "ereport()` level via [ErrorReport::report(self, PgLogLevel)].
     ///
     /// For internal use only
     fn with_location<S: Into<String>>(
@@ -290,7 +290,7 @@ impl ErrorReport {
         self.hint.as_deref()
     }
 
-    /// Report this [PgErrorReport], which will ultimately be reported by Postgres at the specified [PgLogLevel]
+    /// Report this [ErrorReport], which will ultimately be reported by Postgres at the specified [PgLogLevel]
     ///
     /// If the provided `level` is >= [`PgLogLevel::ERROR`] this function will not return.
     pub fn report(self, level: PgLogLevel) {

pgrx-sql-entity-graph/src/aggregate/aggregate_type.rs

@@ -11,7 +11,7 @@
 
 `#[pg_aggregate]` related type metadata for Rust to SQL translation
 
-> Like all of the [`sql_entity_graph`][crate::pgrx_sql_entity_graph] APIs, this is considered **internal**
+> Like all of the [`sql_entity_graph`][crate] APIs, this is considered **internal**
 to the `pgrx` framework and very subject to change between versions. While you may use this, please do it with caution.
 
 */

pgrx-sql-entity-graph/src/aggregate/entity.rs

@@ -11,7 +11,7 @@
 
 `#[pg_aggregate]` related entities for Rust to SQL translation
 
-> Like all of the [`sql_entity_graph`][crate::pgrx_sql_entity_graph] APIs, this is considered **internal**
+> Like all of the [`sql_entity_graph`][crate] APIs, this is considered **internal**
 to the `pgrx` framework and very subject to change between versions. While you may use this, please do it with caution.
 
 
@@ -48,67 +48,67 @@ pub struct PgAggregateEntity {
 
     /// The `arg_data_type` list.
     ///
-    /// Corresponds to `Args` in [`pgrx::aggregate::Aggregate`].
+    /// Corresponds to `Args` in `pgrx::aggregate::Aggregate`.
     pub args: Vec<AggregateTypeEntity>,
 
     /// The direct argument list, appearing before `ORDER BY` in ordered set aggregates.
     ///
-    /// Corresponds to `OrderBy` in [`pgrx::aggregate::Aggregate`].
+    /// Corresponds to `OrderBy` in `pgrx::aggregate::Aggregate`.
     pub direct_args: Option<Vec<AggregateTypeEntity>>,
 
     /// The `STYPE` and `name` parameter for [`CREATE AGGREGATE`](https://www.postgresql.org/docs/current/sql-createaggregate.html)
     ///
-    /// The implementor of an [`pgrx::aggregate::Aggregate`].
+    /// The implementor of an `pgrx::aggregate::Aggregate`.
     pub stype: AggregateTypeEntity,
 
     /// The `SFUNC` parameter for [`CREATE AGGREGATE`](https://www.postgresql.org/docs/current/sql-createaggregate.html)
     ///
-    /// Corresponds to `state` in [`pgrx::aggregate::Aggregate`].
+    /// Corresponds to `state` in `pgrx::aggregate::Aggregate`.
     pub sfunc: &'static str,
 
     /// The `FINALFUNC` parameter for [`CREATE AGGREGATE`](https://www.postgresql.org/docs/current/sql-createaggregate.html)
     ///
-    /// Corresponds to `finalize` in [`pgrx::aggregate::Aggregate`].
+    /// Corresponds to `finalize` in `pgrx::aggregate::Aggregate`.
     pub finalfunc: Option<&'static str>,
 
     /// The `FINALFUNC_MODIFY` parameter for [`CREATE AGGREGATE`](https://www.postgresql.org/docs/current/sql-createaggregate.html)
     ///
-    /// Corresponds to `FINALIZE_MODIFY` in [`pgrx::aggregate::Aggregate`].
+    /// Corresponds to `FINALIZE_MODIFY` in `pgrx::aggregate::Aggregate`.
     pub finalfunc_modify: Option<FinalizeModify>,
 
     /// The `COMBINEFUNC` parameter for [`CREATE AGGREGATE`](https://www.postgresql.org/docs/current/sql-createaggregate.html)
     ///
-    /// Corresponds to `combine` in [`pgrx::aggregate::Aggregate`].
+    /// Corresponds to `combine` in `pgrx::aggregate::Aggregate`.
     pub combinefunc: Option<&'static str>,
 
     /// The `SERIALFUNC` parameter for [`CREATE AGGREGATE`](https://www.postgresql.org/docs/current/sql-createaggregate.html)
     ///
-    /// Corresponds to `serial` in [`pgrx::aggregate::Aggregate`].
+    /// Corresponds to `serial` in `pgrx::aggregate::Aggregate`.
     pub serialfunc: Option<&'static str>,
 
     /// The `DESERIALFUNC` parameter for [`CREATE AGGREGATE`](https://www.postgresql.org/docs/current/sql-createaggregate.html)
     ///
-    /// Corresponds to `deserial` in [`pgrx::aggregate::Aggregate`].
+    /// Corresponds to `deserial` in `pgrx::aggregate::Aggregate`.
     pub deserialfunc: Option<&'static str>,
 
     /// The `INITCOND` parameter for [`CREATE AGGREGATE`](https://www.postgresql.org/docs/current/sql-createaggregate.html)
     ///
-    /// Corresponds to `INITIAL_CONDITION` in [`pgrx::aggregate::Aggregate`].
+    /// Corresponds to `INITIAL_CONDITION` in `pgrx::aggregate::Aggregate`.
     pub initcond: Option<&'static str>,
 
     /// The `MSFUNC` parameter for [`CREATE AGGREGATE`](https://www.postgresql.org/docs/current/sql-createaggregate.html)
     ///
-    /// Corresponds to `moving_state` in [`pgrx::aggregate::Aggregate`].
+    /// Corresponds to `moving_state` in `pgrx::aggregate::Aggregate`.
     pub msfunc: Option<&'static str>,
 
     /// The `MINVFUNC` parameter for [`CREATE AGGREGATE`](https://www.postgresql.org/docs/current/sql-createaggregate.html)
     ///
-    /// Corresponds to `moving_state_inverse` in [`pgrx::aggregate::Aggregate`].
+    /// Corresponds to `moving_state_inverse` in `pgrx::aggregate::Aggregate`.
     pub minvfunc: Option<&'static str>,
 
     /// The `MSTYPE` parameter for [`CREATE AGGREGATE`](https://www.postgresql.org/docs/current/sql-createaggregate.html)
     ///
-    /// Corresponds to `MovingState` in [`pgrx::aggregate::Aggregate`].
+    /// Corresponds to `MovingState` in `pgrx::aggregate::Aggregate`.
     pub mstype: Option<UsedTypeEntity>,
 
     // The `MSSPACE` parameter for [`CREATE AGGREGATE`](https://www.postgresql.org/docs/current/sql-createaggregate.html)
@@ -117,32 +117,32 @@ pub struct PgAggregateEntity {
     // pub msspace: &'static str,
     /// The `MFINALFUNC` parameter for [`CREATE AGGREGATE`](https://www.postgresql.org/docs/current/sql-createaggregate.html)
     ///
-    /// Corresponds to `moving_state_finalize` in [`pgrx::aggregate::Aggregate`].
+    /// Corresponds to `moving_state_finalize` in `pgrx::aggregate::Aggregate`.
     pub mfinalfunc: Option<&'static str>,
 
     /// The `MFINALFUNC_MODIFY` parameter for [`CREATE AGGREGATE`](https://www.postgresql.org/docs/current/sql-createaggregate.html)
     ///
-    /// Corresponds to `MOVING_FINALIZE_MODIFY` in [`pgrx::aggregate::Aggregate`].
+    /// Corresponds to `MOVING_FINALIZE_MODIFY` in `pgrx::aggregate::Aggregate`.
     pub mfinalfunc_modify: Option<FinalizeModify>,
 
     /// The `MINITCOND` parameter for [`CREATE AGGREGATE`](https://www.postgresql.org/docs/current/sql-createaggregate.html)
     ///
-    /// Corresponds to `MOVING_INITIAL_CONDITION` in [`pgrx::aggregate::Aggregate`].
+    /// Corresponds to `MOVING_INITIAL_CONDITION` in `pgrx::aggregate::Aggregate`.
     pub minitcond: Option<&'static str>,
 
     /// The `SORTOP` parameter for [`CREATE AGGREGATE`](https://www.postgresql.org/docs/current/sql-createaggregate.html)
     ///
-    /// Corresponds to `SORT_OPERATOR` in [`pgrx::aggregate::Aggregate`].
+    /// Corresponds to `SORT_OPERATOR` in `pgrx::aggregate::Aggregate`.
     pub sortop: Option<&'static str>,
 
     /// The `PARALLEL` parameter for [`CREATE AGGREGATE`](https://www.postgresql.org/docs/current/sql-createaggregate.html)
     ///
-    /// Corresponds to `PARALLEL` in [`pgrx::aggregate::Aggregate`].
+    /// Corresponds to `PARALLEL` in `pgrx::aggregate::Aggregate`.
     pub parallel: Option<ParallelOption>,
 
     /// The `HYPOTHETICAL` parameter for [`CREATE AGGREGATE`](https://www.postgresql.org/docs/current/sql-createaggregate.html)
     ///
-    /// Corresponds to `hypothetical` in [`pgrx::aggregate::Aggregate`].
+    /// Corresponds to `hypothetical` in `pgrx::aggregate::Aggregate`.
     pub hypothetical: bool,
     pub to_sql_config: ToSqlConfigEntity,
 }

pgrx-sql-entity-graph/src/aggregate/mod.rs

@@ -11,7 +11,7 @@
 
 `#[pg_aggregate]` related macro expansion for Rust to SQL translation
 
-> Like all of the [`sql_entity_graph`][crate::pgrx_sql_entity_graph] APIs, this is considered **internal**
+> Like all of the [`sql_entity_graph`][crate] APIs, this is considered **internal**
 to the `pgrx` framework and very subject to change between versions. While you may use this, please do it with caution.
 
 

pgrx-sql-entity-graph/src/aggregate/options.rs

@@ -11,7 +11,7 @@
 
 `#[pg_aggregate]` related options for Rust to SQL translation
 
-> Like all of the [`sql_entity_graph`][crate::pgrx_sql_entity_graph] APIs, this is considered **internal**
+> Like all of the [`sql_entity_graph`][crate] APIs, this is considered **internal**
 to the `pgrx` framework and very subject to change between versions. While you may use this, please do it with caution.
 
 */

pgrx-sql-entity-graph/src/control_file.rs

@@ -11,7 +11,7 @@
 
 `pgrx_module_magic!()` related macro expansion for Rust to SQL translation
 
-> Like all of the [`sql_entity_graph`][crate::pgrx_sql_entity_graph] APIs, this is considered **internal**
+> Like all of the [`sql_entity_graph`][crate] APIs, this is considered **internal**
 to the `pgrx` framework and very subject to change between versions. While you may use this, please do it with caution.
 
 */

pgrx-sql-entity-graph/src/extension_sql/entity.rs

@@ -11,7 +11,7 @@
 
 `pgrx::extension_sql!()` related entities for Rust to SQL translation
 
-> Like all of the [`sql_entity_graph`][crate::pgrx_sql_entity_graph] APIs, this is considered **internal**
+> Like all of the [`sql_entity_graph`][crate] APIs, this is considered **internal**
 to the `pgrx` framework and very subject to change between versions. While you may use this, please do it with caution.