rust: keep improving errors & fix some return types

- add more string messages to error! macro invocations for NcPlane & NcCell methods.
- refactor NcPlane.base() to return the NcCell.
- fix cell_prime & NcCell.prime to accept gcluster as &str, as well as cells_load_box.
- fix several return types (u32 instead of NcDimension for counting).

rust/src/cells/methods.rs

@@ -71,7 +71,7 @@ impl NcCell {
     pub fn prime(
         plane: &mut NcPlane,
         cell: &mut NcCell,
-        gcluster: NcEgc,
+        gcluster: &str,
         style: NcStyleMask,
         channels: NcChannelPair,
     ) -> NcResult<u32> {
@@ -447,7 +447,7 @@ impl NcCell {
         lr: &mut NcCell,
         hl: &mut NcCell,
         vl: &mut NcCell,
-        gcluster: NcEgc,
+        gcluster: &str,
     ) -> NcResult<()> {
         error![crate::cells_load_box(
             plane, style, channels, ul, ur, ll, lr, hl, vl, gcluster

rust/src/cells/reimplemented.rs

@@ -3,7 +3,7 @@
 use libc::strcmp;
 
 use crate::{
-    cell_release, NcAlphaBits, NcCell, NcChannel, NcChannelPair, NcColor, NcEgc, NcIntResult,
+    cstring, cell_release, NcAlphaBits, NcCell, NcChannel, NcChannelPair, NcColor, NcEgc, NcIntResult,
     NcPaletteIndex, NcPlane, NcRgb, NcStyleMask, NCCELL_ALPHA_OPAQUE, NCCELL_BGDEFAULT_MASK,
     NCCELL_BG_PALETTE, NCCELL_FGDEFAULT_MASK, NCCELL_FG_PALETTE, NCCELL_NOBACKGROUND_MASK,
     NCCELL_WIDEASIAN_MASK, NCRESULT_ERR, NCRESULT_OK, NCSTYLE_MASK,
@@ -460,18 +460,18 @@ pub fn cell_init(cell: &mut NcCell) {
 pub fn cell_prime(
     plane: &mut NcPlane,
     cell: &mut NcCell,
-    gcluster: NcEgc,
+    gcluster: &str,
     style: NcStyleMask,
     channels: NcChannelPair,
 ) -> NcIntResult {
     cell.stylemask = style;
     cell.channels = channels;
-    unsafe { crate::cell_load(plane, cell, gcluster as u32 as *const i8) }
+    unsafe { crate::cell_load(plane, cell, cstring![gcluster]) }
 }
 
 /// Loads up six cells with the [NcEgc]s necessary to draw a box.
 ///
-/// Returns [NCRESULT_OK] on success, [NCRESULT_ERR] on error.
+/// Returns [NCRESULT_OK] on success or [NCRESULT_ERR] on error.
 ///
 /// On error, any [NcCell]s this function might have loaded before the error
 /// are [cell_release]d. There must be at least six [NcEgc]s in `gcluster`.
@@ -487,10 +487,11 @@ pub fn cells_load_box(
     lr: &mut NcCell,
     hl: &mut NcCell,
     vl: &mut NcCell,
-    gcluster: NcEgc,
+    gcluster: &str,
 ) -> NcIntResult {
-    // mutable copy for pointer arithmetics:
-    let mut gclu = gcluster as u32 as *const i8;
+    // TODO: CHECK: mutable copy for pointer arithmetics:
+    let mut gclu = cstring![gcluster];
+
     let mut ulen: NcIntResult;
 
     ulen = cell_prime(plane, ul, gcluster, style, channels);

rust/src/direct/methods.rs

@@ -41,7 +41,7 @@ impl NcDirect {
     ///
     /// *C style function: [ncdirect_stop()][crate::ncdirect_stop].*
     pub fn stop(&mut self) -> NcResult<()> {
-        error![unsafe { crate::ncdirect_stop(self) }]
+        error![unsafe { crate::ncdirect_stop(self) }, "NcDirect.stop()"]
     }
 }
 
@@ -51,14 +51,14 @@ impl NcDirect {
     ///
     /// *C style function: [ncdirect_clear()][crate::ncdirect_clear].*
     pub fn clear(&mut self) -> NcResult<()> {
-        error![unsafe { crate::ncdirect_clear(self) }]
+        error![unsafe { crate::ncdirect_clear(self) }, "NcDirect.clear()"]
     }
 
     /// Forces a flush.
     ///
     /// *C style function: [ncdirect_flush()][crate::ncdirect_flush].*
     pub fn flush(&self) -> NcResult<()> {
-        error![unsafe { crate::ncdirect_flush(self) }]
+        error![unsafe { crate::ncdirect_flush(self) }, "NcDirect.clear()"]
     }
 
     /// Takes the result of [render_frame()][NcDirect#method.render_frame]
@@ -71,7 +71,7 @@ impl NcDirect {
     pub fn raster_frame(&mut self, faken: &mut NcPlane, align: NcAlign) -> NcResult<()> {
         error![
             unsafe { crate::ncdirect_raster_frame(self, faken, align) },
-            "Rastering frame"
+            "NcDirect.raster_frame()"
         ]
     }
 
@@ -95,7 +95,13 @@ impl NcDirect {
         scale: NcScale,
     ) -> NcResult<&'a mut NcPlane> {
         let res = unsafe { crate::ncdirect_render_frame(self, cstring![filename], blitter, scale) };
-        error_ref_mut![res, "Rendering frame"]
+        error_ref_mut![
+            res,
+            &format!(
+                "NcDirect.render_frame({:?}, {:?}, {:?})",
+                filename, blitter, scale
+            )
+        ]
     }
 
     /// Displays an image using the specified blitter and scaling.
@@ -115,9 +121,15 @@ impl NcDirect {
         blitter: NcBlitter,
         scale: NcScale,
     ) -> NcResult<()> {
-        error![unsafe {
-            crate::ncdirect_render_image(self, cstring![filename], align, blitter, scale)
-        }]
+        error![
+            unsafe {
+                crate::ncdirect_render_image(self, cstring![filename], align, blitter, scale)
+            },
+            &format!(
+                "NcDirect.render_image({:?}, {:?}, {:?}, {:?})",
+                filename, align, blitter, scale
+            )
+        ]
     }
 }
 
@@ -127,14 +139,20 @@ impl NcDirect {
     ///
     /// *C style function: [ncdirect_set_fg_palindex()][crate::ncdirect_set_fg_palindex].*
     pub fn set_fg_palindex(&mut self, index: NcPaletteIndex) -> NcResult<()> {
-        error![unsafe { crate::ncdirect_set_fg_palindex(self, index as i32) }]
+        error![
+            unsafe { crate::ncdirect_set_fg_palindex(self, index as i32) },
+            &format!("NcDirect.set_fg_palindex({})", index)
+        ]
     }
 
     /// Sets the background [NcPaletteIndex].
     ///
     /// *C style function: [ncdirect_set_bg_palindex()][crate::ncdirect_set_bg_palindex].*
     pub fn set_bg_palindex(&mut self, index: NcPaletteIndex) -> NcResult<()> {
-        error![unsafe { crate::ncdirect_set_bg_palindex(self, index as i32) }]
+        error![
+            unsafe { crate::ncdirect_set_bg_palindex(self, index as i32) },
+            &format!("NcDirect.set_fg_palindex({})", index)
+        ]
     }
 
     /// Returns the number of simultaneous colors claimed to be supported.
@@ -146,7 +164,7 @@ impl NcDirect {
     pub fn palette_size(&self) -> NcResult<u32> {
         let res = unsafe { crate::ncdirect_palette_size(self) };
         if res == 1 {
-            return Err(NcError::with_msg(1, "No color support"));
+            return Err(NcError::with_msg(1, "No color support ← NcDirect.palette_size()"));
         }
         Ok(res)
     }
@@ -155,64 +173,90 @@ impl NcDirect {
     ///
     /// *C style function: [ncdirect_set_fg_rgb()][crate::ncdirect_set_fg_rgb].*
     pub fn set_fg_rgb(&mut self, rgb: NcRgb) -> NcResult<()> {
-        error![unsafe { crate::ncdirect_set_fg_rgb(self, rgb) }]
+        error![
+            unsafe { crate::ncdirect_set_fg_rgb(self, rgb) },
+            &format!("NcDirect.set_fg_rgb({})", rgb)
+        ]
     }
 
     /// Sets the background [NcRgb].
     ///
     /// *C style function: [ncdirect_set_bg_rgb()][crate::ncdirect_set_bg_rgb].*
     pub fn set_bg_rgb(&mut self, rgb: NcRgb) -> NcResult<()> {
-        error![unsafe { crate::ncdirect_set_bg_rgb(self, rgb) }]
+        error![
+            unsafe { crate::ncdirect_set_bg_rgb(self, rgb) },
+            &format!("NcDirect.set_bg_rgb({})", rgb)
+        ]
     }
 
     /// Sets the foreground [NcColor] components.
     ///
     /// *C style function: [ncdirect_set_fg_rgb8()][crate::ncdirect_set_fg_rgb8].*
     pub fn set_fg_rgb8(&mut self, red: NcColor, green: NcColor, blue: NcColor) -> NcResult<()> {
-        error![crate::ncdirect_set_fg_rgb8(self, red, green, blue)]
+        error![
+            crate::ncdirect_set_fg_rgb8(self, red, green, blue),
+            &format!("NcDirect.set_fg_rgb8({}, {}, {})", red, green, blue)
+        ]
     }
 
     /// Sets the background [NcColor] components.
     ///
     /// *C style function: [ncdirect_set_bg_rgb()][crate::ncdirect_set_bg_rgb].*
     pub fn set_bg_rgb8(&mut self, red: NcColor, green: NcColor, blue: NcColor) -> NcResult<()> {
-        error![crate::ncdirect_set_bg_rgb8(self, red, green, blue)]
+        error![
+            crate::ncdirect_set_bg_rgb8(self, red, green, blue),
+            &format!("NcDirect.set_bg_rgb8({}, {}, {})", red, green, blue)
+        ]
     }
 
     /// Removes the specified styles.
     ///
     /// *C style function: [ncdirect_off_styles()][crate::ncdirect_off_styles].*
     pub fn styles_off(&mut self, stylebits: NcStyleMask) -> NcResult<()> {
-        let res = unsafe { crate::ncdirect_off_styles(self, stylebits.into()) };
-        error![res]
+        error![
+            unsafe { crate::ncdirect_off_styles(self, stylebits.into()) },
+            &format!("NcDirect.styles_off({:0X})", stylebits)
+        ]
     }
 
     /// Adds the specified styles.
     ///
     /// *C style function: [ncdirect_on_styles()][crate::ncdirect_on_styles].*
     pub fn styles_on(&mut self, stylebits: NcStyleMask) -> NcResult<()> {
-        error![unsafe { crate::ncdirect_on_styles(self, stylebits.into()) }]
+        error![
+            unsafe { crate::ncdirect_on_styles(self, stylebits.into()) },
+            &format!("NcDirect.styles_on({:0X})", stylebits)
+        ]
     }
 
     /// Sets just the specified styles.
     ///
     /// *C style function: [ncdirect_set_styles()][crate::ncdirect_set_styles].*
     pub fn styles_set(&mut self, stylebits: NcStyleMask) -> NcResult<()> {
-        error![unsafe { crate::ncdirect_set_styles(self, stylebits.into()) }]
+        error![
+            unsafe { crate::ncdirect_set_styles(self, stylebits.into()) },
+            &format!("NcDirect.styles_set({:0X})", stylebits)
+        ]
     }
 
     /// Indicates to use the "default color" for the foreground.
     ///
     /// *C style function: [ncdirect_set_fg_default()][crate::ncdirect_set_fg_default].*
     pub fn set_fg_default(&mut self) -> NcResult<()> {
-        error![unsafe { crate::ncdirect_set_fg_default(self) }]
+        error![
+            unsafe { crate::ncdirect_set_fg_default(self) },
+            "NcDirect.set_fg_default()"
+        ]
     }
 
     /// Indicates to use the "default color" for the background.
     ///
     /// *C style function: [ncdirect_set_bg_default()][crate::ncdirect_set_bg_default].*
     pub fn set_bg_default(&mut self) -> NcResult<()> {
-        error![unsafe { crate::ncdirect_set_bg_default(self) }]
+        error![
+            unsafe { crate::ncdirect_set_bg_default(self) },
+            "NcDirect.set_bg_default()"
+        ]
     }
 }
 
@@ -240,42 +284,60 @@ impl NcDirect {
     ///
     /// *C style function: [ncdirect_cursor_disable()][crate::ncdirect_cursor_disable].*
     pub fn cursor_disable(&mut self) -> NcResult<()> {
-        error![unsafe { crate::ncdirect_cursor_disable(self) }]
+        error![
+            unsafe { crate::ncdirect_cursor_disable(self) },
+            "NcDirect.cursor_disable()"
+        ]
     }
 
     /// Enables the terminal's cursor, if supported.
     ///
     /// *C style function: [ncdirect_cursor_enable()][crate::ncdirect_cursor_enable].*
     pub fn cursor_enable(&mut self) -> NcResult<()> {
-        error![unsafe { crate::ncdirect_cursor_enable(self) }]
+        error![
+            unsafe { crate::ncdirect_cursor_enable(self) },
+            "NcDirect.cursor_enable()"
+        ]
     }
 
     /// Moves the cursor down, `num` rows.
     ///
     /// *C style function: [ncdirect_cursor_down()][crate::ncdirect_cursor_down].*
     pub fn cursor_down(&mut self, num: NcDimension) -> NcResult<()> {
-        error![unsafe { crate::ncdirect_cursor_down(self, num as i32) }]
+        error![
+            unsafe { crate::ncdirect_cursor_down(self, num as i32) },
+            &format!("NcDirect.cursor_down({})", num)
+        ]
     }
 
     /// Moves the cursor left, `num` columns.
     ///
     /// *C style function: [ncdirect_cursor_left()][crate::ncdirect_cursor_left].*
     pub fn cursor_left(&mut self, num: NcDimension) -> NcResult<()> {
-        error![unsafe { crate::ncdirect_cursor_left(self, num as i32) }]
+        error![
+            unsafe { crate::ncdirect_cursor_left(self, num as i32) },
+            &format!("NcDirect.cursor_left({})", num)
+        ]
     }
 
     /// Moves the cursor right, `num` columns.
     ///
     /// *C style function: [ncdirect_cursor_right()][crate::ncdirect_cursor_right].*
     pub fn cursor_right(&mut self, num: NcDimension) -> NcResult<()> {
-        error![unsafe { crate::ncdirect_cursor_right(self, num as i32) }]
+        error![
+            unsafe { crate::ncdirect_cursor_right(self, num as i32) },
+            &format!("NcDirect.cursor_right({})", num)
+        ]
     }
 
     /// Moves the cursor up, `num` rows.
     ///
     /// *C style function: [ncdirect_cursor_up()][crate::ncdirect_cursor_up].*
     pub fn cursor_up(&mut self, num: NcDimension) -> NcResult<()> {
-        error![unsafe { crate::ncdirect_cursor_up(self, num as i32) }]
+        error![
+            unsafe { crate::ncdirect_cursor_up(self, num as i32) },
+            &format!("NcDirect.cursor_up({})", num)
+        ]
     }
 
     /// Moves the cursor in direct mode to the specified row, column.
@@ -440,9 +502,15 @@ impl NcDirect {
     /// Note that it does not explicitly flush output buffers, so it will not
     /// necessarily be immediately visible.
     ///
+    /// It will fail if the NcDirect context and the foreground channel
+    /// are both marked as using the default color.
+    ///
     /// *C style function: [ncdirect_putstr()][crate::ncdirect_putstr].*
     pub fn putstr(&mut self, channels: NcChannelPair, string: &str) -> NcResult<()> {
-        error![unsafe { crate::ncdirect_putstr(self, channels, cstring![string]) }]
+        error![
+            unsafe { crate::ncdirect_putstr(self, channels, cstring![string]) },
+            &format!("NcDirect.putstr({:0X}, {:?})", channels, string)
+        ]
     }
 
     /// Draws a box with its upper-left corner at the current cursor position,
@@ -467,20 +535,24 @@ impl NcDirect {
         x_len: NcDimension,
         ctlword: u32,
     ) -> NcResult<()> {
-        error![unsafe {
-            let wchars = core::mem::transmute(wchars);
-            crate::ncdirect_box(
-                self,
-                ul,
-                ur,
-                ll,
-                lr,
-                wchars,
-                y_len as i32,
-                x_len as i32,
-                ctlword,
-            )
-        }]
+        error![
+            unsafe {
+                let wchars = core::mem::transmute(wchars);
+                crate::ncdirect_box(
+                    self,
+                    ul,
+                    ur,
+                    ll,
+                    lr,
+                    wchars,
+                    y_len as i32,
+                    x_len as i32,
+                    ctlword,
+                )
+            },
+            &format!("NcDirect.box({:0X}, {:0X}, {:0X}, {:0X}, {:?}, {}, {}, {})",
+                ul, ur, ll, lr, wchars, y_len, x_len, ctlword)
+        ]
     }
 
     /// NcDirect.[box()][NcDirect#method.box] with the double box-drawing characters.

rust/src/plane/methods.rs

@@ -94,7 +94,10 @@ impl NcPlane {
         nc: &mut Notcurses,
         options: NcPlaneOptions,
     ) -> NcResult<&'a mut NcPlane> {
-        error_ref_mut![unsafe { crate::ncpile_create(nc, &options) }]
+        error_ref_mut![
+            unsafe { crate::ncpile_create(nc, &options) },
+            &format!["NcPlane::with_options(Notcurses, {:?})", options]
+        ]
     }
 
     /// New NcPlane, bound to another NcPlane.
@@ -121,7 +124,7 @@ impl NcPlane {
     ) -> NcResult<&'a mut NcPlane> {
         error_ref_mut![
             unsafe { crate::ncplane_create(bound_to, &options) },
-            &format!["NcPlane::with_options({:?}, {:?})", bound_to, options]
+            &format!("NcPlane::with_options_bound(NcPlane, {:?})", options)
         ]
     }
 
@@ -146,7 +149,7 @@ impl NcPlane {
     ///
     /// *C style function: [ncplane_destroy()][crate::ncplane_destroy].*
     pub fn destroy(&mut self) -> NcResult<()> {
-        error![unsafe { crate::ncplane_destroy(self) }]
+        error![unsafe { crate::ncplane_destroy(self) }, "NcPlane.destroy()"]
     }
 }
 
@@ -173,14 +176,20 @@ impl NcPlane {
     ///
     /// *C style function: [ncplane_set_fg_alpha()][crate::ncplane_set_fg_alpha].*
     pub fn set_fg_alpha(&mut self, alpha: NcAlphaBits) -> NcResult<()> {
-        error![unsafe { crate::ncplane_set_fg_alpha(self, alpha as i32) }]
+        error![
+            unsafe { crate::ncplane_set_fg_alpha(self, alpha as i32) },
+            &format!("NcPlane.set_fg_alpha({:0X})", alpha)
+        ]
     }
 
     /// Sets the background [NcAlphaBits] for this NcPlane.
     ///
     /// *C style function: [ncplane_set_bg_alpha()][crate::ncplane_set_bg_alpha].*
     pub fn set_bg_alpha(&mut self, alpha: NcAlphaBits) -> NcResult<()> {
-        error![unsafe { crate::ncplane_set_bg_alpha(self, alpha as i32) }]
+        error![
+            unsafe { crate::ncplane_set_bg_alpha(self, alpha as i32) },
+            &format!("NcPlane.set_bg_alpha({:0X})", alpha)
+        ]
     }
 }
 
@@ -236,8 +245,7 @@ impl NcPlane {
     /// Sets the given [NcChannelPair]s throughout the specified region,
     /// keeping content and attributes unchanged.
     ///
-    /// Returns the number of cells set, or [NCRESULT_ERR]
-    /// on failure.
+    /// Returns the number of cells set.
     ///
     /// *C style function: [ncplane_stain()][crate::ncplane_stain].*
     pub fn stain(
@@ -248,10 +256,17 @@ impl NcPlane {
         ur: NcChannelPair,
         ll: NcChannelPair,
         lr: NcChannelPair,
-    ) -> NcResult<NcDimension> {
+    ) -> NcResult<u32> {
         let res =
             unsafe { crate::ncplane_stain(self, y_stop as i32, x_stop as i32, ul, ur, ll, lr) };
-        error![res, "", res as NcDimension];
+        error![
+            res,
+            &format!(
+                "NcPlane.stain({}, {}, {:0X}, {:0X}, {:0X}, {:0X})",
+                y_stop, x_stop, ul, ur, ll, lr
+            ),
+            res as u32
+        ]
     }
 }
 
@@ -401,8 +416,7 @@ impl NcPlane {
     /// Sets the given style throughout the specified region, keeping content
     /// and channels unchanged.
     ///
-    /// Returns the number of cells set, or [NCRESULT_ERR]
-    /// on failure.
+    /// Returns the number of cells set.
     ///
     /// *C style function: [ncplane_format()][crate::ncplane_format].*
     pub fn format(
@@ -413,7 +427,11 @@ impl NcPlane {
     ) -> NcResult<NcDimension> {
         let res =
             unsafe { crate::ncplane_format(self, y_stop as i32, x_stop as i32, stylemask as u32) };
-        error![res, "", res as NcDimension]
+        error![
+            res,
+            &format!("NcPlane.format({}, {}, {:0X})", y_stop, x_stop, stylemask),
+            res as u32
+        ]
     }
 
     /// Returns the current styling for this NcPlane.
@@ -491,7 +509,10 @@ impl NcPlane {
     ) -> NcResult<NcEgc> {
         let egc = unsafe { crate::ncplane_at_cursor(self, stylemask, channels) };
         if egc.is_null() {
-            return Err(NcError::new(NCRESULT_ERR));
+            return Err(NcError::with_msg(
+                NCRESULT_ERR,
+                &format!("NcPlane.at_cursor({:0X}, {:0X})", stylemask, channels),
+            ));
         }
         let egc = core::char::from_u32(unsafe { *egc } as u32).expect("wrong char");
         Ok(egc)
@@ -506,7 +527,11 @@ impl NcPlane {
     #[inline]
     pub fn at_cursor_cell(&mut self, cell: &mut NcCell) -> NcResult<u32> {
         let bytes = unsafe { crate::ncplane_at_cursor_cell(self, cell) };
-        error![bytes, "", bytes as u32]
+        error![
+            bytes,
+            &format!("NcPlane.at_cursor_cell({:?})", cell),
+            bytes as u32
+        ]
     }
 
     /// Retrieves the current contents of the specified [NcCell], returning the
@@ -524,7 +549,11 @@ impl NcPlane {
     ) -> NcResult<NcEgc> {
         let egc = unsafe { crate::ncplane_at_yx(self, y as i32, x as i32, stylemask, channels) };
         if egc.is_null() {
-            return Err(NcError::new(NCRESULT_ERR));
+            return Err(NcError::with_msg(
+                NCRESULT_ERR,
+                &format!("NcPlane.at_yx({}, {}, {:0X}, {:0X})",
+                y, x, stylemask, channels),
+            ));
         }
         let egc = core::char::from_u32(unsafe { *egc } as u32).expect("wrong char");
         Ok(egc)
@@ -544,7 +573,11 @@ impl NcPlane {
         cell: &mut NcCell,
     ) -> NcResult<u32> {
         let bytes = unsafe { crate::ncplane_at_yx_cell(self, y as i32, x as i32, cell) };
-        error![bytes, "", bytes as u32]
+        error![
+            bytes,
+            &format!("NcPlane.at_yx_cell({}, {}, {:?})", y, x, cell),
+            bytes as u32
+        ]
     }
 
     /// Extracts this NcPlane's base [NcCell] into `cell`.
@@ -552,15 +585,14 @@ impl NcPlane {
     /// The reference is invalidated if this NcPlane is destroyed.
     ///
     /// *C style function: [ncplane_base()][crate::ncplane_base].*
-    pub fn base(&mut self, cell: &mut NcCell) -> NcResult<()> {
-        error![unsafe { crate::ncplane_base(self, cell) }]
+    pub fn base(&mut self) -> NcResult<NcCell> {
+        let mut cell = NcCell::new();
+        let res = unsafe { crate::ncplane_base(self, &mut cell) };
+        error![res, "NcPlane.base()", cell]
     }
 
     /// Sets this NcPlane's base [NcCell] from its components.
     ///
-    /// This function must be called with an empty `egc`.
-    /// `egc` must be a single extended grapheme cluster.
-    ///
     /// It will be used for purposes of rendering anywhere that the NcPlane's
     /// gcluster is 0.
     ///
@@ -585,7 +617,7 @@ impl NcPlane {
         error![
             res,
             &format!(
-                "NcPlane.set_base({:?}, {:0x}, {:0x})",
+                "NcPlane.set_base({:?}, {:0X}, {:0X})",
                 egc, stylemask, channels
             ),
             res as u32
@@ -594,18 +626,17 @@ impl NcPlane {
 
     /// Sets this NcPlane's base NcCell.
     ///
-    /// This function must be called with a zero `cell`.
-    ///
     /// It will be used for purposes of rendering anywhere that the NcPlane's
     /// gcluster is 0.
     ///
     /// Erasing the NcPlane does not reset the base cell.
     ///
     /// *C style function: [ncplane_set_base_cell()][crate::ncplane_set_base_cell].*
-    //
-    // FIXME: documentation: https://github.com/dankamongmen/notcurses/issues/1238
     pub fn set_base_cell(&mut self, cell: &NcCell) -> NcResult<()> {
-        error![unsafe { crate::ncplane_set_base_cell(self, cell) }]
+        error![
+            unsafe { crate::ncplane_set_base_cell(self, cell) },
+            &format!("NcPlane.base({:?})", cell)
+        ]
     }
 
     /// Creates a flat string from the NcEgc's of the selected region of the
@@ -671,7 +702,11 @@ impl NcPlane {
         cell: &NcCell,
     ) -> NcResult<NcDimension> {
         let res = unsafe { crate::ncplane_putc_yx(self, y as i32, x as i32, cell) };
-        error![res, "", res as NcDimension]
+        error![
+            res,
+            &format!("NcPlane.putc_yx({}, {}, {:?})", y, x, cell),
+            res as NcDimension
+        ]
     }
 
     /// Replaces the NcCell at the current coordinates with the provided NcCell,
@@ -683,7 +718,11 @@ impl NcPlane {
     /// *C style function: [ncplane_putc()][crate::ncplane_putc].*
     pub fn putc(&mut self, cell: &NcCell) -> NcResult<NcDimension> {
         let res = crate::ncplane_putc(self, cell);
-        error![res, "", res as NcDimension]
+        error![
+            res,
+            &format!("NcPlane.putc({:?})", cell),
+            res as NcDimension
+        ]
     }
 
     /// Calls [putchar_yx][NcPlane#method.putchar_yx] at the current cursor location.
@@ -693,7 +732,11 @@ impl NcPlane {
     /// *C style function: [ncplane_putchar()][crate::ncplane_putchar].*
     pub fn putchar(&mut self, ch: char) -> NcResult<NcDimension> {
         let res = crate::ncplane_putchar(self, ch);
-        error![res, "", res as NcDimension]
+        error![
+            res,
+            &format!("NcPlane.putchar({:?})", ch),
+            res as NcDimension
+        ]
     }
 
     // TODO: call put_egc
@@ -717,7 +760,11 @@ impl NcPlane {
         ch: char,
     ) -> NcResult<NcDimension> {
         let res = crate::ncplane_putchar_yx(self, y, x, ch);
-        error![res, "", res as NcDimension]
+        error![
+            res,
+            &format!("NcPlane.putchar_yx({}, {}, {:?})", y, x, ch),
+            res as NcDimension
+        ]
     }
 
     /// Writes a series of [NcEgc][crate::NcEgc]s to the current location,
@@ -733,7 +780,11 @@ impl NcPlane {
     #[inline]
     pub fn putstr(&mut self, string: &str) -> NcResult<NcDimension> {
         let res = crate::ncplane_putstr(self, string);
-        error![res, "", res as NcDimension]
+        error![
+            res,
+            &format!("NcPlane.putstr({:?})", string),
+            res as NcDimension
+        ]
     }
 
     /// Same as [putstr][NcPlane#method.putstr], but it also tries to move the
@@ -765,7 +816,7 @@ impl NcPlane {
         let res = unsafe { crate::ncplane_putstr_aligned(self, y as i32, align, cstring![string]) };
         error![
             res,
-            &format!("NcPlane.putstr_aligned({}, {}, {})", y, align, string),
+            &format!("NcPlane.putstr_aligned({}, {}, {:?})", y, align, string),
             res as NcDimension
         ]
     }
@@ -783,7 +834,11 @@ impl NcPlane {
     /// *C style function: [ncplane_putstr_stained()][crate::ncplane_putstr_stained].*
     pub fn putstr_stained(&mut self, string: &str) -> NcResult<NcDimension> {
         let res = unsafe { crate::ncplane_putstr_stained(self, cstring![string]) };
-        error![res, "", res as NcDimension]
+        error![
+            res,
+            &format!("NcPlane.putstr_stained({:?})", string),
+            res as NcDimension
+        ]
     }
 
     /// Write a string, which is a series of [NcEgc][crate::NcEgc]s, to the
@@ -805,7 +860,11 @@ impl NcPlane {
         string: &str,
     ) -> NcResult<NcDimension> {
         let res = unsafe { crate::ncplane_putstr_yx(self, y as i32, x as i32, cstring![string]) };
-        error![res, "", res as NcDimension]
+        error![
+            res,
+            &format!("NcPlane.putstr_yx({}, {}, {:?})", y, x, string),
+            res as NcDimension
+        ]
     }
 }
 
@@ -869,21 +928,30 @@ impl NcPlane {
     //
     // CHECK: whether a negative offset is valid
     pub fn move_yx(&mut self, y: NcOffset, x: NcOffset) -> NcResult<()> {
-        error![unsafe { crate::ncplane_move_yx(self, y, x) }]
+        error![
+            unsafe { crate::ncplane_move_yx(self, y, x) },
+            &format!("NcPlane.move_yx({}, {})", y, x)
+        ]
     }
 
     /// Returns the NcPlane above this one, or None if already at the top.
     ///
     /// *C style function: [ncplane_above()][crate::ncplane_above].*
     pub fn above<'a>(&'a mut self) -> NcResult<&'a mut NcPlane> {
-        error_ref_mut![unsafe { crate::ncplane_above(self) }]
+        error_ref_mut![
+            unsafe { crate::ncplane_above(self) },
+            "NcPlane.above()"
+        ]
     }
 
     /// Returns the NcPlane below this one, or None if already at the bottom.
     ///
     /// *C style function: [ncplane_below()][crate::ncplane_below].*
     pub fn below<'a>(&'a mut self) -> NcResult<&'a mut NcPlane> {
-        error_ref_mut![unsafe { crate::ncplane_below(self) }]
+        error_ref_mut![
+            unsafe { crate::ncplane_below(self) },
+            "NcPlane.below()"
+        ]
     }
 
     /// Relocates this NcPlane above the `above` NcPlane, in the z-buffer.
@@ -893,7 +961,10 @@ impl NcPlane {
     ///
     /// *C style function: [ncplane_move_above()][crate::ncplane_move_above].*
     pub fn move_above(&mut self, above: &mut NcPlane) -> NcResult<()> {
-        error![unsafe { crate::ncplane_move_above(self, above) }]
+        error![
+            unsafe { crate::ncplane_move_above(self, above) },
+            "NcPlane.move_above(NcPlane)"
+        ]
     }
 
     /// Relocates this NcPlane below the `below` NcPlane, in the z-buffer.
@@ -903,7 +974,10 @@ impl NcPlane {
     ///
     /// *C style function: [ncplane_move_below()][crate::ncplane_move_below].*
     pub fn move_below(&mut self, below: &mut NcPlane) -> NcResult<()> {
-        error![unsafe { crate::ncplane_move_below(self, below) }]
+        error![
+            unsafe { crate::ncplane_move_below(self, below) },
+            "NcPlane.move_below(NcPlane)"
+        ]
     }
 
     /// Merges `source` down onto this NcPlane.
@@ -929,8 +1003,8 @@ impl NcPlane {
         target_y: NcDimension,
         target_x: NcDimension,
     ) -> NcResult<()> {
-        error![unsafe {
-            crate::ncplane_mergedown(
+        error![
+            unsafe { crate::ncplane_mergedown(
                 source,
                 self,
                 source_y as i32,
@@ -939,8 +1013,10 @@ impl NcPlane {
                 len_x as i32,
                 target_y as i32,
                 target_x as i32,
-            )
-        }]
+            )},
+            &format!("NcPlane.mergedown(NcPlane, {}, {}, {}, {}, {}, {})",
+                source_y, source_x, len_y, len_x, target_y, target_x)
+        ]
     }
 
     /// Merges `source` down onto this NcPlane.
@@ -956,7 +1032,10 @@ impl NcPlane {
     // TODO: maybe create a reversed method, and/or an associated function,
     // for `mergedown` too.
     pub fn mergedown_simple(&mut self, source: &NcPlane) -> NcResult<()> {
-        error![unsafe { crate::ncplane_mergedown_simple(source, self) }]
+        error![
+            unsafe { crate::ncplane_mergedown_simple(source, self) },
+            "NcPlane.mergedown_simple(NcPlane)"
+        ]
     }
 
     /// Gets the parent to which this NcPlane is bound, if any.
@@ -965,16 +1044,22 @@ impl NcPlane {
     //
     // TODO: CHECK: what happens when it's bound to itself.
     pub fn parent<'a>(&'a mut self) -> NcResult<&'a mut NcPlane> {
-        error_ref_mut![unsafe { crate::ncplane_parent(self) }]
+        error_ref_mut![
+            unsafe { crate::ncplane_parent(self) },
+            "NcPlane.parent()"
+        ]
     }
 
     /// Gets the parent to which this NcPlane is bound, if any.
     ///
     /// *C style function: [ncplane_parent_const()][crate::ncplane_parent_const].*
     //
-    // TODO: CHECK: what happens when it's bound to itself.
+    // CHECK: what happens when it's bound to itself.
     pub fn parent_const<'a>(&'a self) -> NcResult<&'a NcPlane> {
-        error_ref![unsafe { crate::ncplane_parent_const(self) }]
+        error_ref![
+            unsafe { crate::ncplane_parent_const(self) },
+            "NcPlane.parent_const()"
+        ]
     }
 
     /// Unbounds this NcPlane from its parent, makes it a bound child of
@@ -990,7 +1075,10 @@ impl NcPlane {
     ///
     /// *C style function: [ncplane_reparent()][crate::ncplane_reparent].*
     pub fn reparent<'a>(&mut self, newparent: &'a mut NcPlane) -> NcResult<&'a mut NcPlane> {
-        error_ref_mut![unsafe { crate::ncplane_reparent(self, newparent) }]
+        error_ref_mut![
+            unsafe { crate::ncplane_reparent(self, newparent) },
+            "NcPlane.reparent(NcPlane)"
+        ]
     }
 
     /// Like [`reparent`][NcPlane#method.reparent], except any bound
@@ -1002,7 +1090,10 @@ impl NcPlane {
     //
     // TODO:CHECK: If 'newparent' is an ancestor, NULL is returned & no changes're made.
     pub fn reparent_family<'a>(&mut self, newparent: &'a mut NcPlane) -> NcResult<&'a mut NcPlane> {
-        error_ref_mut![unsafe { crate::ncplane_reparent_family(self, newparent) }]
+        error_ref_mut![
+            unsafe { crate::ncplane_reparent_family(self, newparent) },
+            "NcPlane.reparent_family(NcPlane)"
+        ]
     }
 
     /// Makes the physical screen match the last rendered frame from the pile of
@@ -1013,7 +1104,7 @@ impl NcPlane {
     ///
     /// *C style function: [ncpile_rasterize()][crate::ncpile_rasterize].*
     pub fn rasterize<'a>(&mut self) -> NcResult<()> {
-        error![unsafe { crate::ncpile_rasterize(self) }]
+        error![unsafe { crate::ncpile_rasterize(self) }, "NcPlane.rasterize()"]
     }
 
     /// Renders the pile of which this NcPlane is a part.
@@ -1022,21 +1113,27 @@ impl NcPlane {
     ///
     /// *C style function: [ncpile_render()][crate::ncpile_render].*
     pub fn render<'a>(&mut self) -> NcResult<()> {
-        error![unsafe { crate::ncpile_render(self) }]
+        error![unsafe { crate::ncpile_render(self) }, "NcPlane.render()"]
     }
 
     /// Gets a mutable reference to the [Notcurses] context of this NcPlane.
     ///
     /// *C style function: [ncplane_notcurses()][crate::ncplane_notcurses].*
     pub fn notcurses<'a>(&mut self) -> NcResult<&'a mut Notcurses> {
-        error_ref_mut![unsafe { crate::ncplane_notcurses(self) }]
+        error_ref_mut![
+            unsafe { crate::ncplane_notcurses(self) },
+            "NcPlane.notcurses()"
+        ]
     }
 
     /// Gets an immutable reference to the [Notcurses] context of this NcPlane.
     ///
     /// *C style function: [ncplane_notcurses_const()][crate::ncplane_notcurses_const].*
     pub fn notcurses_const<'a>(&self) -> NcResult<&'a Notcurses> {
-        error_ref![unsafe { crate::ncplane_notcurses_const(self) }]
+        error_ref![
+            unsafe { crate::ncplane_notcurses_const(self) },
+            "NcPlane.notcurses()"
+        ]
     }
 }
 
@@ -1087,7 +1184,10 @@ impl NcPlane {
     ///
     /// *C style function: [ncplane_cursor_move_yx()][crate::ncplane_cursor_move_yx].*
     pub fn cursor_move_yx(&mut self, y: NcDimension, x: NcDimension) -> NcResult<()> {
-        error![unsafe { crate::ncplane_cursor_move_yx(self, y as i32, x as i32) }]
+        error![
+            unsafe { crate::ncplane_cursor_move_yx(self, y as i32, x as i32) },
+            &format!("NcPlane.move_yx({}, {})", y, x)
+        ]
     }
 
     /// Moves the cursor to the specified row within this NcPlane.
@@ -1095,7 +1195,10 @@ impl NcPlane {
     /// *(No equivalent C style function)*
     pub fn cursor_move_y(&mut self, y: NcDimension) -> NcResult<()> {
         let x = self.cursor_x();
-        error![unsafe { crate::ncplane_cursor_move_yx(self, y as i32, x as i32) }]
+        error![
+            unsafe { crate::ncplane_cursor_move_yx(self, y as i32, x as i32) },
+            &format!("NcPlane.move_y({})", y)
+        ]
     }
 
     /// Moves the cursor to the specified column within this NcPlane.
@@ -1103,7 +1206,10 @@ impl NcPlane {
     /// *(No equivalent C style function)*
     pub fn cursor_move_x(&mut self, x: NcDimension) -> NcResult<()> {
         let y = self.cursor_y();
-        error![unsafe { crate::ncplane_cursor_move_yx(self, y as i32, x as i32) }]
+        error![
+            unsafe { crate::ncplane_cursor_move_yx(self, y as i32, x as i32) },
+            &format!("NcPlane.move_x({})", x)
+        ]
     }
 
     /// Moves the cursor the number of rows specified (forward or backwards).
@@ -1139,7 +1245,10 @@ impl NcPlane {
     /// *C style function: [ncplane_align()][crate::ncplane_align].*
     #[inline]
     pub fn align(&mut self, align: NcAlign, cols: NcDimension) -> NcResult<()> {
-        error![crate::ncplane_align(self, align, cols)]
+        error![
+            crate::ncplane_align(self, align, cols),
+            &format!("NcPlane.align({:?}, {})", align, cols)
+        ]
     }
 
     ///
@@ -1229,8 +1338,8 @@ impl NcPlane {
         y_len: NcDimension,
         x_len: NcDimension,
     ) -> NcResult<()> {
-        error![unsafe {
-            crate::ncplane_resize(
+        error![
+            unsafe { crate::ncplane_resize(
                 self,
                 keep_y as i32,
                 keep_x as i32,
@@ -1240,8 +1349,10 @@ impl NcPlane {
                 x_off as i32,
                 y_len as i32,
                 x_len as i32,
-            )
-        }]
+            )},
+            &format!("NcPlane.resize({}, {}, {}, {}, {}, {}, {}, {})",
+                keep_y, keep_x, keep_len_y, keep_len_x, y_off, x_off, y_len, x_len)
+        ]
     }
 
     /// Realigns this NcPlane against its parent, using the alignment specified