From 8a062e94c3d1a4dce279513c21c4b689346ee9bb Mon Sep 17 00:00:00 2001 From: Wolfgang Bumiller Date: Wed, 25 Nov 2020 15:13:57 +0100 Subject: [PATCH] more doc improvements Signed-off-by: Wolfgang Bumiller --- perlmod-macro/src/lib.rs | 2 +- perlmod/src/array.rs | 18 +++++++++--------- perlmod/src/ffi.rs | 6 ++++++ perlmod/src/hash.rs | 4 ++-- perlmod/src/value.rs | 4 ++-- 5 files changed, 20 insertions(+), 14 deletions(-) diff --git a/perlmod-macro/src/lib.rs b/perlmod-macro/src/lib.rs index 045e33a..e330fdd 100644 --- a/perlmod-macro/src/lib.rs +++ b/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); diff --git a/perlmod/src/array.rs b/perlmod/src/array.rs index 3efa39d..ce6e112 100644 --- a/perlmod/src/array.rs +++ b/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> { diff --git a/perlmod/src/ffi.rs b/perlmod/src/ffi.rs index cb673fb..5b01e5a 100644 --- a/perlmod/src/ffi.rs +++ b/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, diff --git a/perlmod/src/hash.rs b/perlmod/src/hash.rs index 6463d88..688f989 100644 --- a/perlmod/src/hash.rs +++ b/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, } diff --git a/perlmod/src/value.rs b/perlmod/src/value.rs index cc4d271..c722b44 100644 --- a/perlmod/src/value.rs +++ b/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),