Merge pull request #1395 from felinira/wip/fina/docs-cleanup

sdroege · web-flow · commit 7cd06421c502 · 2024-06-06T20:25:55.000+03:00
docs: Fix broken links / cleanup README
diff --git a/gdk-pixbuf/src/subclass/pixbuf_animation.rs b/gdk-pixbuf/src/subclass/pixbuf_animation.rs
@@ -1,7 +1,7 @@
 // Take a look at the license at the top of the repository in the LICENSE file.
 
 // rustdoc-stripper-ignore-next
-//! Traits intended for subclassing [`PixbufAnimation`](crate::PixbufAnimation).
+//! Traits intended for subclassing [`PixbufAnimation`].
 
 use std::{
     mem::MaybeUninit,
diff --git a/gdk-pixbuf/src/subclass/pixbuf_animation_iter.rs b/gdk-pixbuf/src/subclass/pixbuf_animation_iter.rs
@@ -1,7 +1,7 @@
 // Take a look at the license at the top of the repository in the LICENSE file.
 
 // rustdoc-stripper-ignore-next
-//! Traits intended for subclassing [`PixbufAnimationIter`](crate::PixbufAnimationIter).
+//! Traits intended for subclassing [`PixbufAnimationIter`].
 
 use std::{
     sync::OnceLock,
diff --git a/gdk-pixbuf/src/subclass/pixbuf_loader.rs b/gdk-pixbuf/src/subclass/pixbuf_loader.rs
@@ -1,7 +1,7 @@
 // Take a look at the license at the top of the repository in the LICENSE file.
 
 // rustdoc-stripper-ignore-next
-//! Traits intended for subclassing [`PixbufLoader`](crate::PixbufLoader).
+//! Traits intended for subclassing [`PixbufLoader`].
 
 use glib::{prelude::*, subclass::prelude::*, translate::*};
 
diff --git a/glib-macros/src/lib.rs b/glib-macros/src/lib.rs
@@ -1219,8 +1219,8 @@ pub fn cstr_bytes(item: TokenStream) -> TokenStream {
 /// | --- | --- | --- | --- |
 /// | `name = "literal"` | The name of the property | field ident where `_` (leading and trailing `_` are trimmed) is replaced into `-` | `#[property(name = "prop-name")]` |
 /// | `type = expr` | The type of the property | inferred | `#[property(type = i32)]` |
-/// | `get [= expr]` | Specify that the property is readable and use `PropertyGet::get` [or optionally set a custom internal getter] | | `#[property(get)]`, `#[property(get = get_prop)]`, or `[property(get = \|_\| 2)]` |
-/// | `set [= expr]` | Specify that the property is writable and use `PropertySet::set` [or optionally set a custom internal setter] | | `#[property(set)]`, `#[property(set = set_prop)]`, or `[property(set = \|_, val\| {})]` |
+/// | `get [= expr]` | Specify that the property is readable and use [`PropertyGet::get`] [or optionally set a custom internal getter] | | `#[property(get)]`, `#[property(get = get_prop)]`, or `[property(get = \|_\| 2)]` |
+/// | `set [= expr]` | Specify that the property is writable and use [`PropertySet::set`] [or optionally set a custom internal setter] | | `#[property(set)]`, `#[property(set = set_prop)]`, or `[property(set = \|_, val\| {})]` |
 /// | `override_class = expr` | The type of class of which to override the property from | | `#[property(override_class = SomeClass)]` |
 /// | `override_interface = expr` | The type of interface of which to override the property from | | `#[property(override_interface = SomeInterface)]` |
 /// | `nullable` | Whether to use `Option<T>` in the generated setter method |  | `#[property(nullable)]` |
@@ -1256,32 +1256,32 @@ pub fn cstr_bytes(item: TokenStream) -> TokenStream {
 /// by assigning an expression to `get`/`set` `#[property]` attributes: `#[property(get = |_| 2, set)]` or `#[property(get, set = custom_setter_func)]`.
 ///
 /// # Supported types
-/// Every type implementing the trait `Property` is supported.
-/// The type `Option<T>` is supported as a property only if `Option<T>` implements `ToValueOptional`.
+/// Every type implementing the trait [`Property`] is supported.
+/// The type `Option<T>` is supported as a property only if `Option<T>` implements [`ToValueOptional`].
 /// Optional types also require the `nullable` attribute: without it, the generated setter on the wrapper type
 /// will take `T` instead of `Option<T>`, preventing the user from ever calling the setter with a `None` value.
 ///
 /// ## Adding support for custom types
-/// ### Types wrapping an existing `T: glib::value::ToValue + glib::HasParamSpec`
+/// ### Types wrapping an existing <code>T: [ToValue] + [HasParamSpec]</code>
 /// If you have declared a newtype as
 /// ```rust
 /// struct MyInt(i32);
 /// ```
-/// you can use it as a property by deriving `glib::ValueDelegate`.
+/// you can use it as a property by deriving [`ValueDelegate`].
 ///
 /// ### Types with inner mutability
-/// The trait `glib::Property` must be implemented.
-/// The traits `PropertyGet` and `PropertySet` should be implemented to enable the Properties macro
+/// The trait [`Property`] must be implemented.
+/// The traits [`PropertyGet`] and [`PropertySet`] should be implemented to enable the Properties macro
 /// to generate a default internal getter/setter.
-/// If possible, implementing `PropertySetNested` is preferred over `PropertySet`, because it
+/// If possible, implementing [`PropertySetNested`] is preferred over `PropertySet`, because it
 /// enables this macro to access the contained type and provide access to its fields,
 /// using the `member = $structfield` syntax.
 ///
-/// ### Types without `glib::HasParamSpec`
-/// If you have encountered a type `T: glib::value::ToValue`, inside the `gtk-rs` crate, which doesn't implement `HasParamSpec`,
+/// ### Types without [`HasParamSpec`][HasParamSpec]
+/// If you have encountered a type <code>T: [ToValue]</code>, inside the gtk-rs crate, which doesn't implement [`HasParamSpec`][HasParamSpec],
 /// then it's a bug and you should report it.
-/// If you need to support a `ToValue` type with a `ParamSpec` not provided by `gtk-rs`, then you need to
-/// implement `glib::HasParamSpec` on that type.
+/// If you need to support a `ToValue` type with a [`ParamSpec`] not provided by gtk-rs, then you need to
+/// implement `HasParamSpec` on that type.
 ///
 /// # Example
 /// ```
@@ -1348,6 +1348,18 @@ pub fn cstr_bytes(item: TokenStream) -> TokenStream {
 ///   assert_eq!(myfoo.fizz(), "custom set: test value".to_string());
 /// }
 /// ```
+///
+/// [`Property`]: ../glib/property/trait.Property.html
+/// [`PropertyGet`]: ../glib/property/trait.PropertyGet.html
+/// [`PropertyGet::get`]: ../glib/property/trait.PropertyGet.html#tymethod.get
+/// [`PropertySet`]: ../glib/property/trait.PropertySet.html
+/// [`PropertySet::set`]: ../glib/property/trait.PropertySet.html#tymethod.set
+/// [`PropertySetNested`]: ../glib/property/trait.PropertySetNested.html
+/// [`ObjectExt::property`]: ../glib/object/trait.ObjectExt.html#tymethod.property
+/// [HasParamSpec]: ../glib/trait.HasParamSpec.html
+/// [`ParamSpec`]: ../glib/struct.ParamSpec.html
+/// [`ToValueOptional`]: ../glib/value/trait.ToValueOptional.html
+/// [ToValue]: ../glib/value/trait.ToValue.html
 #[allow(clippy::needless_doctest_main)]
 #[proc_macro_derive(Properties, attributes(properties, property))]
 pub fn derive_props(input: TokenStream) -> TokenStream {
diff --git a/glib/README.md b/glib/README.md
@@ -23,8 +23,8 @@ Currently, the minimum supported Rust version is `1.70.0`.
 Most types in the GLib family have [`Type`] identifiers.
 Their corresponding Rust types implement the [`StaticType`] trait.
 
-A dynamically typed [`Value`] can carry values of any [`StaticType`].
-[`Variant`](struct@Variant)s can carry values of [`StaticVariantType`].
+A dynamically typed [`Value`] can carry values of any `StaticType`.
+[Variants][`Variant`] can carry values of [`StaticVariantType`].
 
 ## Errors
 
@@ -35,10 +35,11 @@ carry values from various [error domains](error::ErrorDomain) such as
 ## Objects
 
 Each class and interface has a corresponding smart pointer struct
-representing an instance of that type (e.g. [`Object`] for `GObject` or
-`gtk::Widget` for `GtkWidget`). They are reference counted and feature
-interior mutability similarly to Rust's `Rc<RefCell<T>>` idiom.
-Consequently, cloning objects is cheap and their methods never require
+representing an instance of that type (e.g. [`Object`] for [`GObject`] or
+[`gtk4::Widget`] for [`GtkWidget`]). They are reference counted and feature
+interior mutability similarly to Rust's
+[`Rc<RefCell<T>>`]
+idiom. Consequently, cloning objects is cheap and their methods never require
 mutable borrows. Two smart pointers are equal if they point to the same
 object.
 
@@ -48,7 +49,7 @@ marker trait. The [`Cast`] trait enables upcasting
 and downcasting.
 
 Interfaces and non-leaf classes also have corresponding traits (e.g.
-[`ObjectExt`] or `gtk::WidgetExt`), which are blanketly implemented for all
+[`ObjectExt`] or [`WidgetExt`]), which are blanketly implemented for all
 their subtypes.
 
 You can create new subclasses of [`Object`] or other object types. Look at
@@ -60,11 +61,10 @@ GLib-based libraries largely operate on pointers to various boxed or
 reference counted structures so the bindings have to implement corresponding
 smart pointers (wrappers), which encapsulate resource management and safety
 checks. Such wrappers are defined via the
-[`wrapper`][`macro@wrapper`] macro, which uses abstractions
-defined in the [`wrapper`][`mod@wrapper`], [`boxed`][`mod@boxed`],
-[`shared`][`mod@shared`] and [`object`][`mod@object`] modules.
-
-The [`translate`][`mod@translate`] module defines and partly implements
+[`wrapper!`] macro, which uses abstractions
+defined in the [`wrapper`], [`boxed`],
+[`shared`] and [`object`][mod@object] modules.
+The [`translate`] module defines and partly implements
 conversions between high level Rust types (including the aforementioned
 wrappers) and their FFI counterparts.
 
@@ -99,3 +99,26 @@ glib = { git = "https://github.com/gtk-rs/gtk-rs-core.git", package = "glib" }
 ## License
 
 __glib__ is available under the MIT License, please refer to it.
+
+[`Type`]: https://gtk-rs.org/gtk-rs-core/stable/latest/docs/glib/types/struct.Type.html
+[`StaticType`]: https://gtk-rs.org/gtk-rs-core/stable/latest/docs/glib/types/trait.StaticType.html
+[`Value`]: https://gtk-rs.org/gtk-rs-core/stable/latest/docs/glib/value/struct.Value.html
+[`Variant`]: https://gtk-rs.org/gtk-rs-core/stable/latest/docs/glib/variant/struct.Variant.html
+[`StaticVariantType`]: https://gtk-rs.org/gtk-rs-core/stable/latest/docs/glib/variant/trait.StaticVariantType.html
+[`Error`]: https://gtk-rs.org/gtk-rs-core/stable/latest/docs/glib/error/struct.Error.html
+[`FileError`]: https://gtk-rs.org/gtk-rs-core/stable/latest/docs/glib/enum.FileError.html
+[`Object`]: https://gtk-rs.org/gtk-rs-core/stable/latest/docs/glib/object/struct.Object.html
+[`GObject`]: https://docs.gtk.org/gobject/class.Object.html
+[`gtk4::Widget`]: https://gtk-rs.org/gtk4-rs/stable/latest/docs/gtk4/struct.Widget.html
+[`GtkWidget`]: https://docs.gtk.org/gtk4/class.Widget.html
+[`Rc<RefCell<T>>`]: https://doc.rust-lang.org/stable/core/cell/index.html#introducing-mutability-inside-of-something-immutable
+[`IsA`]: https://gtk-rs.org/gtk-rs-core/stable/latest/docs/glib/object/trait.IsA.html
+[`Cast`]: https://gtk-rs.org/gtk-rs-core/stable/latest/docs/glib/object/trait.Cast.html
+[`ObjectExt`]: https://gtk-rs.org/gtk-rs-core/stable/latest/docs/glib/object/trait.ObjectExt.html
+[`WidgetExt`]: https://gtk-rs.org/gtk4-rs/stable/latest/docs/gtk4/prelude/trait.WidgetExt.html
+[`wrapper!`]: https://gtk-rs.org/gtk-rs-core/stable/latest/docs/glib/macro.wrapper.html
+[`wrapper`]: https://gtk-rs.org/gtk-rs-core/stable/latest/docs/glib/wrapper/index.html
+[`boxed`]: https://gtk-rs.org/gtk-rs-core/stable/latest/docs/glib/boxed/index.html
+[`shared`]: https://gtk-rs.org/gtk-rs-core/stable/latest/docs/glib/shared/index.html
+[mod@object]: https://gtk-rs.org/gtk-rs-core/stable/latest/docs/glib/object/index.html
+[`translate`]: https://gtk-rs.org/gtk-rs-core/stable/latest/docs/glib/translate/index.html
diff --git a/glib/src/collections/ptr_slice.rs b/glib/src/collections/ptr_slice.rs
@@ -11,7 +11,7 @@ const MIN_SIZE: usize = 16;
 // rustdoc-stripper-ignore-next
 /// Slice of elements of type `T` allocated by the GLib allocator.
 ///
-/// The underlying memory is always `NULL`-terminated. [`Slice<T>`]
+/// The underlying memory is always `NULL`-terminated. [`Slice<T>`](crate::collections::slice::Slice)
 /// can be used for a non-`NULL`-terminated slice.
 ///
 /// This can be used like a `&[T]`, `&mut [T]` and `Vec<T>`.
diff --git a/glib/src/gstring.rs b/glib/src/gstring.rs
@@ -134,7 +134,7 @@ impl GStr {
     ///
     /// # Safety
     ///
-    /// See [`CStr::from_ptr`](CStr::from_ptr#safety).
+    /// See [`CStr::from_ptr`](std::ffi::CStr#safety).
     #[inline]
     pub unsafe fn from_ptr<'a>(ptr: *const c_char) -> &'a Self {
         let cstr = CStr::from_ptr(ptr);
@@ -177,7 +177,7 @@ impl GStr {
     // rustdoc-stripper-ignore-next
     /// Converts this GLib string to a byte slice containing the trailing 0 byte.
     ///
-    /// This function is the equivalent of [`GStr::to_bytes`] except that it will retain the
+    /// This function is the equivalent of [`GStr::as_bytes`] except that it will retain the
     /// trailing nul terminator instead of chopping it off.
     #[inline]
     pub const fn as_bytes_with_nul(&self) -> &[u8] {
@@ -669,9 +669,9 @@ impl<'a> ToGlibPtr<'a, *mut c_char> for GStr {
 }
 
 // rustdoc-stripper-ignore-next
-/// `NULL`-terminated UTF-8 string as stored in [`StrV`].
+/// `NULL`-terminated UTF-8 string as stored in [`StrV`](crate::StrV).
 ///
-/// Unlike [`&GStr`] this does not have its length stored.
+/// Unlike [`&GStr`](crate::GStr) this does not have its length stored.
 #[repr(transparent)]
 pub struct GStringPtr(ptr::NonNull<c_char>);
 
@@ -685,7 +685,7 @@ impl GlibPtrDefault for GStringPtr {
 
 impl GStringPtr {
     // rustdoc-stripper-ignore-next
-    /// Returns the corresponding [`&GStr`].
+    /// Returns the corresponding [`&GStr`](crate::GStr).
     #[inline]
     pub fn to_gstr(&self) -> &GStr {
         unsafe { GStr::from_ptr(self.0.as_ptr()) }
@@ -699,7 +699,7 @@ impl GStringPtr {
     }
 
     // rustdoc-stripper-ignore-next
-    /// This is just an alias for [`as_str`].
+    /// This is just an alias for [`as_str`](GStringPtr::as_str).
     #[inline]
     #[deprecated = "Use as_str instead"]
     pub fn to_str(&self) -> &str {
@@ -1029,7 +1029,7 @@ impl GString {
     /// [`Arguments`](std::fmt::Arguments) instance can be created with the
     /// [`format_args!`](std::format_args) macro.
     ///
-    /// Please note that using [`gformat!`] might be preferable.
+    /// Please note that using [`gformat!`](crate::gformat) might be preferable.
     pub fn format(args: fmt::Arguments) -> Self {
         if let Some(s) = args.as_str() {
             return Self::from(s);
diff --git a/glib/src/gstring_builder.rs b/glib/src/gstring_builder.rs
@@ -146,7 +146,7 @@ impl GStringBuilder {
     }
 
     // rustdoc-stripper-ignore-next
-    /// Finalizes the builder, converting it to a [`GString`].
+    /// Finalizes the builder, converting it to a [`GString`](crate::GString).
     #[must_use = "String returned from the builder should probably be used"]
     #[inline]
     pub fn into_string(self) -> crate::GString {
diff --git a/glib/src/lib.rs b/glib/src/lib.rs
@@ -3,6 +3,26 @@
 #![cfg_attr(docsrs, feature(doc_cfg))]
 #![allow(clippy::missing_safety_doc)]
 #![allow(renamed_and_removed_lints)]
+// Override docs references to point to locally generated docs
+// rustdoc-stripper-ignore-next
+//! [`Type`]: struct@Type
+//! [`StaticType`]: trait@types::StaticType
+//! [`Value`]: struct@Value
+//! [`Variant``]: struct@Variant
+//! [`StaticVariantType`]: trait@variant::StaticVariantType
+//! [`Error`]: struct@Error
+//! [`FileError`]: enum@FileError
+//! [`Object`]: struct@Object
+//! [`Rc<RefCell<T>>`]: mod@std::cell#introducing-mutability-inside-of-something-immutable
+//! [`IsA`]: trait@object::IsA
+//! [`Cast`]: trait@object::Cast
+//! [`ObjectExt`]: trait@object::ObjectExt
+//! [`wrapper!`]: macro@wrapper
+//! [`wrapper`]: mod@wrapper
+//! [`boxed`]: mod@boxed
+//! [`shared`]: mod@shared
+//! [mod@object]: mod@object
+//! [`translate`]: mod@translate
 #![doc = include_str!("../README.md")]
 
 pub use bitflags;
diff --git a/glib/src/log.rs b/glib/src/log.rs
@@ -544,7 +544,7 @@ macro_rules! g_log {
 ///
 /// [g_log]: https://docs.gtk.org/glib/func.log.html
 ///
-/// It is the same as calling the [`g_log!`] macro with [`LogLevel::Error`].
+/// It is the same as calling the [`g_log!`](crate::g_log!) macro with [`LogLevel::Error`].
 ///
 /// Example:
 ///
@@ -581,7 +581,7 @@ macro_rules! g_error {
 ///
 /// [g_log]: https://docs.gtk.org/glib/func.log.html
 ///
-/// It is the same as calling the [`g_log!`] macro with [`LogLevel::Critical`].
+/// It is the same as calling the [`g_log!`](crate::g_log!) macro with [`LogLevel::Critical`].
 ///
 /// Example:
 ///
@@ -618,7 +618,7 @@ macro_rules! g_critical {
 ///
 /// [g_log]: https://docs.gtk.org/glib/func.log.html
 ///
-/// It is the same as calling the [`g_log!`] macro with [`LogLevel::Warning`].
+/// It is the same as calling the [`g_log!`](crate::g_log!) macro with [`LogLevel::Warning`].
 ///
 /// Example:
 ///
@@ -655,7 +655,7 @@ macro_rules! g_warning {
 ///
 /// [g_log]: https://docs.gtk.org/glib/func.log.html
 ///
-/// It is the same as calling the [`g_log!`] macro with [`LogLevel::Message`].
+/// It is the same as calling the [`g_log!`](crate::g_log!) macro with [`LogLevel::Message`].
 ///
 /// Example:
 ///
@@ -692,7 +692,7 @@ macro_rules! g_message {
 ///
 /// [g_log]: https://docs.gtk.org/glib/func.log.html
 ///
-/// It is the same as calling the [`g_log!`] macro with [`LogLevel::Info`].
+/// It is the same as calling the [`g_log!`](crate::g_log!) macro with [`LogLevel::Info`].
 ///
 /// Example:
 ///
@@ -729,7 +729,7 @@ macro_rules! g_info {
 ///
 /// [g_log]: https://docs.gtk.org/glib/func.log.html
 ///
-/// It is the same as calling the [`g_log!`] macro with [`LogLevel::Debug`].
+/// It is the same as calling the [`g_log!`](crate::g_log!) macro with [`LogLevel::Debug`].
 ///
 /// Example:
 ///
diff --git a/glib/src/object.rs b/glib/src/object.rs
@@ -1931,7 +1931,7 @@ pub trait ObjectExt: ObjectType {
     /// in C. This can be achieved with a closure that watches an object: see the documentation
     /// of the [`closure!`](crate::closure!) macro for more details.
     ///
-    /// Same as [`Self::connect`] but takes a [`Closure`](crate::Closure) instead of a `Fn`.
+    /// Same as [`Self::connect`] but takes a [`Closure`] instead of a `Fn`.
     #[doc(alias = "g_signal_connect_closure")]
     #[doc(alias = "g_signal_connect_object")]
     fn connect_closure(
@@ -1950,7 +1950,7 @@ pub trait ObjectExt: ObjectType {
     /// This panics if the signal does not exist.
     ///
     /// Same as [`Self::connect_closure`] but takes a
-    /// [`SignalId`](crate::subclass::signal::SignalId) instead of a signal name.
+    /// [`SignalId`] instead of a signal name.
     #[doc(alias = "g_signal_connect_closure_by_id")]
     fn connect_closure_id(
         &self,
diff --git a/glib/src/param_spec.rs b/glib/src/param_spec.rs
@@ -1890,7 +1890,7 @@ impl ParamSpecOverride {
     }
 
     // rustdoc-stripper-ignore-next
-    /// Similar to [`ParamSpecOverride::new`] but specific for an interface.
+    /// Create a [`ParamSpecOverride`] to override an interface property.
     ///
     /// # Examples
     ///
@@ -1915,7 +1915,7 @@ impl ParamSpecOverride {
     }
 
     // rustdoc-stripper-ignore-next
-    /// Similar to [`ParamSpecOverride::new`] but specific for a class.
+    /// Create a [`ParamSpecOverride`] to override a class property.
     ///
     /// # Examples
     ///
diff --git a/glib/src/subclass/object.rs b/glib/src/subclass/object.rs

Original file line number	Diff line number	Diff line change
`@@ -146,7 +146,7 @@ impl GStringBuilder {`
`146`	`146`	`}`
`147`	`147`
`148`	`148`	`// rustdoc-stripper-ignore-next`
`149`		- /// Finalizes the builder, converting it to a [`GString`].
	`149`	+ /// Finalizes the builder, converting it to a [`GString`](crate::GString).
`150`	`150`	`#[must_use = "String returned from the builder should probably be used"]`
`151`	`151`	`#[inline]`
`152`	`152`	`pub fn into_string(self) -> crate::GString {`