more doc improvements

Signed-off-by: Wolfgang Bumiller <w.bumiller@proxmox.com>

perlmod-macro/src/lib.rs

@@ -74,7 +74,7 @@ pub fn package(attr: TokenStream_1, item: TokenStream_1) -> TokenStream_1 {
 }
 
 /// Attribute to export a function so that it can be installed as an `xsub` in perl. See the
-/// [`package!`] macro for a usage example.
+/// [`package!`](macro@package) macro for a usage example.
 #[proc_macro_attribute]
 pub fn export(attr: TokenStream_1, item: TokenStream_1) -> TokenStream_1 {
     let attr = parse_macro_input!(attr as AttributeArgs);

perlmod/src/array.rs

@@ -1,4 +1,4 @@
-//! Module dealing with perl [`Array`]s. (`AV` pointers).
+//! Module dealing with perl [`Array`](crate::Array)s. ([`AV`](crate::ffi::AV) pointers).
 
 use std::convert::TryFrom;
 use std::marker::PhantomData;
@@ -21,18 +21,18 @@ impl Array {
         unsafe { Self::from_raw_move(ffi::RSPL_newAV()) }
     }
 
-    /// Turn this into a `Scalar`. The underlying perl value does not change, this is a pure type
+    /// Turn this into a [`Scalar`]. The underlying perl value does not change, this is a pure type
     /// cast down to a less specific "pointer" type.
     pub fn into_scalar(self) -> Scalar {
         self.0
     }
 
-    /// Get the internal perl value as a low-level `AV` pointer.
+    /// Get the internal perl value as a low-level [`AV`] pointer.
     pub fn av(&self) -> *mut AV {
         self.0.sv() as *mut AV
     }
 
-    /// "Downcast" a `Scalar` into an `Array`.
+    /// "Downcast" a [`Scalar`] into an [`Array`].
     ///
     /// # Safety
     ///
@@ -41,7 +41,7 @@ impl Array {
         Self(scalar)
     }
 
-    /// Take over a raw `AV` value, assuming that we then own a reference to it.
+    /// Take over a raw [`AV`] value, assuming that we then own a reference to it.
     ///
     /// # Safety
     ///
@@ -49,13 +49,13 @@ impl Array {
     /// of one reference.
     ///
     /// The caller must ensure that it is safe to decrease the reference count later on, or use
-    /// `into_raw()` instead of letting the `Array` get dropped.
+    /// [`into_raw()`](Value::into_raw()) instead of letting the [`Array`] get dropped.
     pub unsafe fn from_raw_move(ptr: *mut AV) -> Self {
         Self(Scalar::from_raw_move(ptr as *mut SV))
     }
 
-    /// Create a new reference to an existing `AV` value. This will increase the value's reference
-    /// count.
+    /// Create a new reference to an existing [`AV`] value. This will increase the value's
+    /// reference count.
     ///
     /// # Safety
     ///
@@ -170,7 +170,7 @@ impl std::fmt::Debug for Array {
 
 /// An iterator over a perl array.
 ///
-/// Technically the iterator always holds a reference count on the `AV` pointer, but we still
+/// Technically the iterator always holds a reference count on the [`AV`] pointer, but we still
 /// distinguish between an iterator going over a borrowed [`Array`] and one coming from
 /// [`IntoIterator`](std::iter::IntoIterator).
 pub struct Iter<'a> {

perlmod/src/ffi.rs

@@ -3,26 +3,31 @@
 //! You should not use this code directly. This is used by the binding generator to implement xsubs
 //! for exported functions.
 
+/// Raw perl subroutine pointer value. This should not be used directly.
 #[repr(C)]
 pub struct CV {
     _ffi: usize,
 }
 
+/// Raw scalar-ish perl value. This should not be used directly.
 #[repr(C)]
 pub struct SV {
     _ffi: usize,
 }
 
+/// Raw perl array value. This should not be used directly.
 #[repr(C)]
 pub struct AV {
     _ffi: usize,
 }
 
+/// Raw perl hash value. This should not be used directly.
 #[repr(C)]
 pub struct HV {
     _ffi: usize,
 }
 
+/// Raw perl hash entry iterator. This should not be used directly.
 #[repr(C)]
 pub struct HE {
     _ffi: usize,
@@ -122,6 +127,7 @@ impl StackMark {
     }
 }
 
+/// Iterator over the stack up to the [`StackMark`].
 pub struct StackIter {
     at: usize,
     end: usize,

perlmod/src/hash.rs

@@ -1,4 +1,4 @@
-//! Module dealing with perl [`Hash`]es. (`HV` pointers).
+//! Module dealing with perl [`Hash`](crate::Hash)es. ([`HV`](crate::ffi::HV) pointers).
 
 use std::convert::TryFrom;
 
@@ -174,7 +174,7 @@ impl std::fmt::Debug for Hash {
 ///
 /// Perl hashes have an integrated iterator. Perl goes to great lengths to make it impossible to
 /// properly iterate over a hash without messing with the hash's internal state, so contrary to the
-/// array iterator, this iterator always references an existing [`Hash`].
+/// array iterator, this iterator always references an existing [`Hash`](crate::Hash).
 pub struct Iter<'a> {
     hash: &'a Hash,
 }

perlmod/src/value.rs

@@ -10,8 +10,8 @@ use crate::scalar::ScalarRef;
 use crate::Error;
 use crate::{Array, Hash, Scalar};
 
-/// A higher level value. This is basically an `SV` already cast to `AV` or `HV` for arrays and
-/// hashes.
+/// A higher level value. This is basically an [`SV`] already cast to [`AV`](crate::ffi::AV) or
+/// [`HV`](crate::ffi::HV) for arrays and hashes.
 pub enum Value {
     Scalar(Scalar),
     Reference(Scalar),