rust: improve comments

- use new syntax for doclinks
- improve some comments
- add README

rust/README.md

@@ -0,0 +1,4 @@
+# libnotcurses-sys
+
+[![Crate](https://img.shields.io/crates/v/libnotcurses-sys.svg)](https://crates.io/crates/libnotcurses-sys)
+[![API](https://docs.rs/libnotcurses-sys/badge.svg)](https://docs.rs/libnotcurses-sys)

rust/src/bindings.rs

@@ -1,8 +1,11 @@
 //! Curated re-exports of the `bindgen` bindings
 //!
 //! The full list of bindings is under the
-//! [`bindgen`](../bindgen/index.html) submodule
+//! [`bindgen`] submodule
 //!
+//! This module publicly re-exports bindgen generated functions and constants,
+//! while privately re-exporting other functions, constants and all structs
+//! in order to wrap them up or crate new aliases for them.
 //
 // WARNING: DO NOT EXECUTE RUSTFMT ON THIS FILE.
 // Custom formatting permits easier maintenance.
@@ -14,9 +17,9 @@ pub mod bindgen {
     //! Automatically generated Rust FFI bindings
     //!
     //! All of the notcurses functions and some of the constants are reexported
-    //! by the [`bindings`](../bindings/index.html) module.
+    //! by the [`bindings`] module.
     //! While the structs, enums and some other constants are type aliased in
-    //! the [`types`](../types/index.html) module, in order to follow the
+    //! the [`types`] module, in order to follow the
     //! Rust API Guidelines as much as possible.
     //!
     include!(concat!(env!("OUT_DIR"), "/bindings.rs"));

rust/src/cells.rs

@@ -97,7 +97,7 @@ pub unsafe fn cell_prime(
     unsafe { cell_load(plane, cell, gcluster as u32 as *const i8) }
 }
 
-/// load up six cells with the [Egc](type.Egc.html)s necessary to draw a box.
+/// load up six cells with the [Egc]s necessary to draw a box.
 ///
 /// returns 0 on success, -1 on error.
 ///

rust/src/lib.rs

@@ -1,6 +1,6 @@
 //! `libnotcurses-sys` is an unsafe Rust wrapper for the notcurses C library
 //!
-//! It follows very closely the original C API while following the Rust API Guidelines
+//! It follows very closely the C API, adapted to the Rust API Guidelines.
 //!
 //! For a higher lever API, safer and more idiomatic, take a look at
 //! [notcurses-rs](https://github.com/dankamongmen/notcurses-rs)

rust/src/macros.rs

@@ -3,8 +3,8 @@ use crate::Cell;
 
 // Cell ------------------------------------------------------------------------
 
-/// Initializes a cell providing an [`Egc`](type.Egc.html),
+/// Initializes a cell providing an [`Egc`],
-/// a [`StyleMask`](type.StyleMask.html) and [`Channels`](type.Channels.html)
+/// a [`StyleMask`] and [`Channels`]
 #[macro_export]
 macro_rules! cell_initializer {
     ( $c:expr, $s:expr, $chan:expr  ) => {
@@ -18,7 +18,7 @@ macro_rules! cell_initializer {
     };
 }
 
-/// Initializes a cell providing just an [`Egc`](type.Egc.html),
+/// Initializes a cell providing just an [`Egc`],
 #[macro_export]
 macro_rules! cell_char_initializer {
     ( $c:expr ) => {

rust/src/notcurses.rs

@@ -109,12 +109,12 @@ impl NotcursesOptions {
     ///   can be added without reshaping the struct.
     ///   Undefined bits must be set to 0.
     ///
-    ///   - [`NCOPTION_INHIBIT_SETLOCALE`](type.NCOPTION_INHIBIT_SETLOCALE.html)
+    ///   - [`NCOPTION_INHIBIT_SETLOCALE`]
-    ///   - [`NCOPTION_NO_ALTERNATE_SCREEN`](type.NCOPTION_NO_ALTERNATE_SCREEN.html)
+    ///   - [`NCOPTION_NO_ALTERNATE_SCREEN`]
-    ///   - [`NCOPTION_NO_FONT_CHANGES`](type.NCOPTION_NO_FONT_CHANGES.html)
+    ///   - [`NCOPTION_NO_FONT_CHANGES`]
-    ///   - [`NCOPTION_NO_QUIT_SIGHANDLERS`](type.NCOPTION_NO_QUIT_SIGHANDLERS.html)
+    ///   - [`NCOPTION_NO_QUIT_SIGHANDLERS`]
-    ///   - [`NCOPTION_NO_WINCH_SIGHANDLER`](type.NCOPTION_NO_WINCH_SIGHANDLER.html)
+    ///   - [`NCOPTION_NO_WINCH_SIGHANDLER`]
-    ///   - [`NCOPTION_SUPPRESS_BANNERS`](type.NCOPTION_SUPPRESS_BANNERS.html)
+    ///   - [`NCOPTION_SUPPRESS_BANNERS`]
     ///
     pub fn with_all_options(
         loglevel: NcLogLevel,

rust/src/plane.rs

@@ -191,6 +191,9 @@ impl NcPlaneOptions {
     }
 
     /// `NcplaneOptions` constructor
+    ///
+    /// Note: If you use`NCPLANE_OPTION_HORALIGNED` flag, you must provide
+    /// the `NcAlign` value as the `x` parameter, casted to `i32`.
     pub fn with_all_options(y: i32, x: i32, rows: u32, cols: u32, flags: u64) -> Self {
         NcPlaneOptions {
             y,

rust/src/types/cell.rs

@@ -1,5 +1,5 @@
 // Cell
-/// A coordinate on an [`NcPlane`](type.NcPlane.html) storing 128 bits of data
+/// A coordinate on an [`NcPlane`] storing 128 bits of data
 ///
 /// ```txt
 /// Cell: 128 bits structure comprised of the following 5 elements:
@@ -175,7 +175,7 @@ pub const CELL_WIDEASIAN_MASK: u64 = crate::bindings::CELL_WIDEASIAN_MASK as u64
 pub type Egc = char;
 
 // EgcBackStop
-/// An `u8` always at zero, part of the [`Cell`](type.Cell.html) struct
+/// An `u8` always at zero, part of the [`Cell`] struct
 ///
 /// ```txt
 /// 00000000
@@ -187,7 +187,7 @@ pub type EgcBackstop = u8;
 
 // StyleMask
 ///
-/// An `u16` of `NCSTYLE_*` boolean styling attributes:
+/// An `u16` of `NCSTYLE_*` boolean styling attributes
 ///
 /// ```txt
 /// 11111111 11111111

rust/src/types/channel.rs

@@ -12,7 +12,7 @@
 /// - plus 2 bits of alpha
 /// - plus context-dependent info
 ///
-/// The context details are documented in [`Channels`](type.Channels.html)
+/// The context details are documented in [`Channels`]
 ///
 /// `type in C: channel (uint32_t)`
 ///
@@ -36,7 +36,7 @@ pub type AlphaBits = u32;
 
 // Channels
 //
-/// 64 bits containing a foreground and background [`Channel`](type.Channel.html)
+/// 64 bits containing a foreground and background [`Channel`]
 ///
 /// ```txt
 /// ~~AA~~~~|RRRRRRRR|GGGGGGGG|BBBBBBBB|~~AA~~~~|RRRRRRRR|GGGGGGGG|BBBBBBBB
@@ -141,7 +141,7 @@ pub type Color = u8;
 // NOTE: the order of the colors is different than in Channel.
 pub type NcPixel = u32;
 
-/// Palette structure consisting of an array of 256 [`Channel`](type.Channel.html)s
+/// Palette structure consisting of an array of 256 [`Channel`]s
 ///
 /// Some terminals only support 256 colors, but allow the full
 /// palette to be specified with arbitrary RGB colors. In all cases, it's more
@@ -152,14 +152,14 @@ pub type NcPixel = u32;
 ///
 pub type Palette = crate::palette256;
 
-/// 8-bit value used for indexing into a [`Palette`](type.Palette.html)
+/// 8-bit value used for indexing into a [`Palette`]
 ///
 pub type PaletteIndex = u8;
 
 /// Context for a palette fade operation
 pub type NcFadeCtx = crate::ncfadectx;
 
-/// the [`Egc`](type.Egc.html)s which form the various levels
+/// the [`Egc`]s which form the various levels
 /// of a given geometry.
 ///
 /// If the geometry is wide, things are arranged with the rightmost side

rust/src/types/plane.rs

@@ -9,18 +9,18 @@
 /// `type in C: ncplane (struct)`
 pub type NcPlane = crate::ncplane;
 
-/// Options struct for [`NcPlane`](type.NcPlane.html)
+/// Options struct for [`NcPlane`]
 pub type NcPlaneOptions = crate::ncplane_options;
 
 /// Horizontal alignment relative to the parent plane. Set alignment in 'x'.
 pub const NCPLANE_OPTION_HORALIGNED: u64 = crate::bindings::NCPLANE_OPTION_HORALIGNED as u64;
 
-/// I/O wrapper to dump file descriptor to [`NcPlane`](type.NcPlane.html)
+/// I/O wrapper to dump file descriptor to [`NcPlane`]
 ///
 /// `type in C: ncfdplane (struct)`
 pub type NcFdPlane = crate::ncfdplane;
 
-/// Options struct for [`NcFdPlane`](type.NcFdPlane.html)
+/// Options struct for [`NcFdPlane`]
 ///
 /// `type in C: ncplane_options (struct)`
 pub type NcFdPlaneOptions = crate::ncfdplane_options;
@@ -28,12 +28,16 @@ pub type NcFdPlaneOptions = crate::ncfdplane_options;
 /// Alignment within a plane or terminal.
 /// Left/right-justified, or centered.
 pub type NcAlign = crate::ncalign_e;
+
 /// Align an NcPlane or NcTerm
 pub const NCALIGN_LEFT: NcAlign = crate::ncalign_e_NCALIGN_LEFT;
+
 ///
 pub const NCALIGN_RIGHT: NcAlign = crate::ncalign_e_NCALIGN_RIGHT;
+
 ///
 pub const NCALIGN_CENTER: NcAlign = crate::ncalign_e_NCALIGN_CENTER;
+
 ///
 pub const NCALIGN_UNALIGNED: NcAlign = crate::ncalign_e_NCALIGN_UNALIGNED;
 
@@ -76,7 +80,7 @@ pub const NCBLIT_DEFAULT: NcBlitter = crate::ncblitter_e_NCBLIT_DEFAULT;
 /// not yet implemented
 pub const NCBLIT_SIXEL: NcBlitter = crate::ncblitter_e_NCBLIT_SIXEL;
 
-/// How to scale an [`NcVisual`](type.NcVisual.html) during rendering
+/// How to scale an [`NcVisual`] during rendering
 ///
 /// - NCSCALE_NONE will apply no scaling.
 /// - NCSCALE_SCALE scales a visual to the plane's size,
@@ -94,10 +98,10 @@ pub const NCSCALE_STRETCH: NcScale = crate::ncscale_e_NCSCALE_STRETCH;
 
 /// A visual bit of multimedia opened with LibAV|OIIO
 pub type NcVisual = crate::ncvisual;
-/// Options struct for [`NcVisual`](type.NcVisual.html)
+/// Options struct for [`NcVisual`]
 pub type NcVisualOptions = crate::ncvisual_options;
 
-/// Use [`CELL_ALPHA_BLEND`](constant.CELL_ALPHA_BLEND.html) with visual
+/// Use [`CELL_ALPHA_BLEND`] with visual
 pub const NCVISUAL_OPTION_BLEND: u32 = crate::bindings::NCVISUAL_OPTION_BLEND;
 
 /// Fail rather than degrade

rust/src/types/terminal.rs

@@ -5,7 +5,7 @@
 /// Minimal notcurses instances for styling text
 pub type NcDirect = crate::ncdirect;
 
-/// Flags (options) for [`NcDirect`](type.NcDirect.html)
+/// Flags (options) for [`NcDirect`]
 pub type NcDirectFlags = u64;
 
 /// Flag that avoids placing the terminal into cbreak mode
@@ -35,7 +35,7 @@ pub const NCDIRECT_OPTION_INHIBIT_SETLOCALE: NcDirectFlags =
 ///
 pub type Notcurses = crate::bindings::notcurses;
 
-/// Options struct for [`Notcurses`](type.Notcurses.html)
+/// Options struct for [`Notcurses`]
 pub type NotcursesOptions = crate::bindings::notcurses_options;
 
 /// Do not call setlocale()
@@ -93,7 +93,7 @@ pub const NCOPTION_VERIFY_SIXEL: u64 = crate::bindings::NCOPTION_VERIFY_SIXEL as
 
 // NcLogLevel ------------------------------------------------------------------
 
-/// Log level for [`NotcursesOptions`](type.NotcursesOptions.html)
+/// Log level for [`NotcursesOptions`]
 ///
 /// These log levels consciously map cleanly to those of libav; Notcurses itself
 /// does not use this full granularity. The log level does not affect the opening

rust/src/types/widgets.rs

@@ -18,13 +18,13 @@
 /// `type in C: ncmenu (struct)`
 pub type NcMenu = crate::ncmenu;
 
-/// Options struct for [`NcMenu`](type.NcMenu.html)
+/// Options struct for [`NcMenu`]
 pub type NcMenuOptions = crate::ncmenu_options;
 
-/// Item for [`NcMenu`](type.NcMenu.html)
+/// Item for [`NcMenu`]
 pub type NcMenuItem = crate::ncmenu_item;
 
-/// Section for [`NcMenu`](type.NcMenu.html)
+/// Section for [`NcMenu`]
 pub type NcMenuSection = crate::ncmenu_section;
 
 /// Bottom row (as opposed to top row)
@@ -40,14 +40,14 @@ pub const NCMENU_OPTION_HIDING: u32 = crate::bindings::NCMENU_OPTION_HIDING;
 /// Supports optional readline keybindings (opt out using
 /// NCREADER_OPTION_NOCMDKEYS flag)
 ///
-/// Takes ownership of its [`NcPlane`](type.NcPlane.html), destroying it on any
+/// Takes ownership of its [`NcPlane`], destroying it on any
 /// error (`ncreader_destroy`() otherwise destroys the ncplane).
 ///
 /// `type in C: ncreader (struct)`
 ///
 pub type NcReader = crate::ncreader;
 
-/// Options struct for [`NcReader`](type.NcReader.html)
+/// Options struct for [`NcReader`]
 ///
 /// `type in C: ncreader_options (struct)`
 ///
@@ -83,10 +83,10 @@ pub const NCREADER_OPTION_VERSCROLL: u32 = crate::bindings::NCREADER_OPTION_VERS
 /// Tablets can come and go at any time, and can grow or shrink at any time.
 pub type NcReel = crate::ncreel;
 
-/// Options struct for [`NcReel`](type.NcReel.html)
+/// Options struct for [`NcReel`]
 pub type NcReelOptions = crate::ncreel_options;
 
-/// Visual tablet for [`NcReel`](type.NcReel.html)
+/// Visual tablet for [`NcReel`]
 pub type NcTablet = crate::nctablet;
 
 /// is navigation circular (does moving down from the last tablet move to the
@@ -100,15 +100,15 @@ pub const NCREEL_OPTION_INFINITESCROLL: u32 = crate::bindings::NCREEL_OPTION_INF
 
 // NcPlot ----------------------------------------------------------------------
 
-/// A histogram, bound to an [`NcPlane`](type.NcPlane.html)
+/// A histogram, bound to an [`NcPlane`]
 /// (uses non-negative `f64`s)
 pub type NcPlotF64 = crate::ncdplot;
 
-/// A histogram, bound to an [`NcPlane`](type.NcPlane.html) (uses `u64`s)
+/// A histogram, bound to an [`NcPlane`] (uses `u64`s)
 pub type NcPlotU64 = crate::ncuplot;
 
 /// Options struct for
-/// [`NcPlotF64`](type.NcPlotF64.html) or [`NcPlotU64`](type.NcPlotU64.html)
+/// [`NcPlotF64`] or [`NcPlotU64`]
 pub type NcPlotOptions = crate::ncplot_options;
 
 /// Use domain detection only for max
@@ -130,9 +130,9 @@ pub const NCPLOT_OPTION_VERTICALI: u32 = crate::bindings::NCPLOT_OPTION_VERTICAL
 
 /// high-level widget for selecting one item from a set
 pub type NcSelector = crate::ncselector;
-/// an item for [`NcSelector`](type.NcSelector.html)
+/// an item for [`NcSelector`]
 pub type NcSelectorItem = crate::ncselector_item;
-/// Options structur for [`NcSelector`](type.NcSelector.html)
+/// Options structur for [`NcSelector`]
 pub type NcSelectorOptions = crate::ncselector_options;
 
 // NcStats ---------------------------------------------------------------------
@@ -145,8 +145,8 @@ pub type NcStats = crate::ncstats;
 /// high-level widget for selecting items from a set
 pub type NcMultiSelector = crate::ncmultiselector;
 
-/// an item for [`NcMultiSelector`](type.NcMultiSelector.html)
+/// an item for [`NcMultiSelector`]
 pub type NcMultiSelectorItem = crate::ncmselector_item;
 
-/// Options structure for [`NcMultiSelector`](type.NcMultiSelector.html)
+/// Options structure for [`NcMultiSelector`]
 pub type NcMultiSelectorOptions = crate::ncmultiselector_options;