rust: fix comments

rust/src/bindings.rs

@@ -8,10 +8,10 @@
 // [clippy & bindgen](https://github.com/rust-lang/rust-bindgen/issues/1470)
 #[allow(clippy::all)]
 pub mod ffi {
-    //! Automatically generated Rust FFI bindings, for reference.
+    //! Rust FFI bindings, automatically generated with bindgen.
     //!
-    //! All of the notcurses API functions are reexported to the public API
-    //! while the structs, enums and constants are type aliased or wrapped up.
+    //! Almost all of the notcurses API functions are reexported to the public
+    //! API, while structs, enums and constants are type aliased or wrapped up.
     //!
     include!(concat!(env!("OUT_DIR"), "/bindings.rs"));
 }

rust/src/cells/mod.rs

@@ -67,7 +67,7 @@ mod reimplemented;
 pub use reimplemented::*;
 
 // NcCell
-/// A coordinate on an [`NcPlane`] storing 128 bits of data
+/// A coordinate on an [`NcPlane`][crate::NcPlane] storing 128 bits of data
 ///
 /// An `NcCell` corresponds to a single character cell on some [`NcPlane`],
 /// which can be occupied by a single [`NcEgc`] grapheme cluster (some root
@@ -166,6 +166,9 @@ pub use reimplemented::*;
 ///
 pub type NcCell = crate::bindings::ffi::cell;
 
+#[allow(unused_imports)]
+use crate::{NcAlphaBits, NcChannel, NcPlane};
+
 /// [`NcAlphaBits`] bits indicating
 /// [`NcCell`]'s foreground or background color will be a composite between
 /// its color and the `NcCell`s' corresponding colors underneath it

rust/src/channel/reimplemented.rs

@@ -26,13 +26,13 @@ pub fn channel_set_alpha(channel: &mut NcChannel, alpha: NcAlphaBits) {
     }
 }
 
-/// Gets the foreground [NcAlphabits] from an [NcChannelPair], shifted to LSBs.
+/// Gets the foreground [NcAlphaBits] from an [NcChannelPair], shifted to LSBs.
 #[inline]
 pub const fn channels_fg_alpha(channels: NcChannelPair) -> NcAlphaBits {
     channel_alpha(channels_fchannel(channels))
 }
 
-/// Gets the background [NcAlphabits] from an [NcChannelPair], shifted to LSBs.
+/// Gets the background [NcAlphaBits] from an [NcChannelPair], shifted to LSBs.
 #[inline]
 pub const fn channels_bg_alpha(channels: NcChannelPair) -> NcAlphaBits {
     channel_alpha(channels_bchannel(channels))
@@ -162,7 +162,7 @@ pub fn channel_set_rgb8(channel: &mut NcChannel, r: NcColor, g: NcColor, b: NcCo
     *channel = (*channel & !NCCELL_BG_RGB_MASK) | NCCELL_BGDEFAULT_MASK | rgb;
 }
 
-/// Gets the three foreground RGB [NcColors] from an [NcChannelPair], and
+/// Gets the three foreground RGB [NcColor]s from an [NcChannelPair], and
 /// returns the foreground [NcChannel] (which can have some extra bits set).
 #[inline]
 pub fn channels_fg_rgb8(
@@ -174,7 +174,7 @@ pub fn channels_fg_rgb8(
     channel_rgb8(channels_fchannel(channels), r, g, b)
 }
 
-/// Gets the three background RGB [NcColors] from an [NcChannelPair], and
+/// Gets the three background RGB [NcColor]s from an [NcChannelPair], and
 /// returns the background [NcChannel] (which can have some extra bits set).
 #[inline]
 pub fn channels_bg_rgb8(
@@ -323,7 +323,7 @@ pub fn channels_bg_palindex_p(channels: NcChannelPair) -> bool {
     channel_palindex_p(channels_bchannel(channels))
 }
 
-/// Sets an [NcCell]'s foreground [NcPaletteIndex].
+/// Sets an [NcCell][crate::NcCell]'s foreground [NcPaletteIndex].
 ///
 /// Also sets [NCCELL_FG_PALETTE] and [NCCELL_ALPHA_OPAQUE],
 /// and clears out [NCCELL_FGDEFAULT_MASK].
@@ -336,7 +336,7 @@ pub fn channels_set_fg_palindex(channels: &mut NcChannelPair, index: NcPaletteIn
     *channels |= (index as NcChannelPair) << 32;
 }
 
-/// Sets an [NcCell]'s background [NcPaletteIndex].
+/// Sets an [NcCell][crate::NcCell]'s background [NcPaletteIndex].
 ///
 /// Also sets [NCCELL_BG_PALETTE] and [NCCELL_ALPHA_OPAQUE],
 /// and clears out [NCCELL_BGDEFAULT_MASK].

rust/src/error.rs

@@ -4,12 +4,12 @@
 /// See also [`NCRESULT_OK`] and [`NCRESULT_ERR`].
 pub type NcResult = i32;
 
-/// Value for no errors, for the bindgen functions that return [`NcResult`]
+/// ERROR value, for the functions that return an [`NcResult`]
 ///
 /// Meanwhile the static inline functions reimplemented in Rust return `bool`.
 pub const NCRESULT_OK: i32 = 0;
 
-/// Value for an error, for the bindgen functions that return [`NcResult`]
+/// OK value, for the functions that return [`NcResult`]
 ///
 /// Meanwhile the static inline functions reimplemented in Rust return `bool`.
 pub const NCRESULT_ERR: i32 = -1;

rust/src/macros.rs

@@ -10,10 +10,10 @@ macro_rules! sleep {
     };
 }
 
-/// Renders the [Notcurses] object sleeps for $ms milliseconds.
+/// Renders the [Notcurses][crate::Notcurses] object sleeps for $ms milliseconds.
 #[macro_export]
 macro_rules! rsleep {
-    ($nc: expr, $ms:expr) => {
+    ($nc:expr, $ms:expr) => {
         unsafe {
             crate::notcurses_render($nc);
         }

rust/src/palette/mod.rs

@@ -24,7 +24,8 @@
 mod reimplemented;
 pub use reimplemented::*;
 
-/// NcPalette structure consisting of an array of 256 [`NcChannel`]s.
+/// NcPalette structure consisting of an array of 256
+/// [`NcChannel`][crate::NcChannel]s.
 ///
 /// See also [NcPaletteIndex].
 ///

rust/src/widgets/reader/mod.rs

@@ -21,7 +21,7 @@ mod methods;
 /// Supports optional readline keybindings (opt out using
 /// NCREADER_OPTION_NOCMDKEYS flag)
 ///
-/// Takes ownership of its [`NcPlane`], destroying it on any
+/// Takes ownership of its [`NcPlane`][crate::NcPlane], destroying it on any
 /// error (`ncreader_destroy`() otherwise destroys the ncplane).
 ///
 /// `type in C: ncreader (struct)`