From e23cd63aacc2bb1675daaed7cd17eab77fb79c13 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?joseLu=C3=ADs?= Date: Fri, 20 Nov 2020 20:15:58 +0100 Subject: [PATCH] rust: improve comments - use new syntax for doclinks - improve some comments - add README --- rust/README.md | 4 ++++ rust/src/bindings.rs | 9 ++++++--- rust/src/cells.rs | 2 +- rust/src/lib.rs | 2 +- rust/src/macros.rs | 6 +++--- rust/src/notcurses.rs | 12 ++++++------ rust/src/plane.rs | 3 +++ rust/src/types/cell.rs | 6 +++--- rust/src/types/channel.rs | 10 +++++----- rust/src/types/plane.rs | 16 ++++++++++------ rust/src/types/terminal.rs | 6 +++--- rust/src/types/widgets.rs | 28 ++++++++++++++-------------- 12 files changed, 59 insertions(+), 45 deletions(-) create mode 100644 rust/README.md diff --git a/rust/README.md b/rust/README.md new file mode 100644 index 000000000..45c098529 --- /dev/null +++ b/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) diff --git a/rust/src/bindings.rs b/rust/src/bindings.rs index 391db6d28..6efc50944 100644 --- a/rust/src/bindings.rs +++ b/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")); diff --git a/rust/src/cells.rs b/rust/src/cells.rs index a2c5f3840..8ecb8fe15 100644 --- a/rust/src/cells.rs +++ b/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. /// diff --git a/rust/src/lib.rs b/rust/src/lib.rs index 08316b9f5..84a4bbca1 100644 --- a/rust/src/lib.rs +++ b/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) diff --git a/rust/src/macros.rs b/rust/src/macros.rs index 20d3f9c30..fca48e494 100644 --- a/rust/src/macros.rs +++ b/rust/src/macros.rs @@ -3,8 +3,8 @@ use crate::Cell; // Cell ------------------------------------------------------------------------ -/// Initializes a cell providing an [`Egc`](type.Egc.html), -/// a [`StyleMask`](type.StyleMask.html) and [`Channels`](type.Channels.html) +/// Initializes a cell providing an [`Egc`], +/// 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 ) => { diff --git a/rust/src/notcurses.rs b/rust/src/notcurses.rs index f24d7f564..0b4317df4 100644 --- a/rust/src/notcurses.rs +++ b/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_NO_ALTERNATE_SCREEN`](type.NCOPTION_NO_ALTERNATE_SCREEN.html) - /// - [`NCOPTION_NO_FONT_CHANGES`](type.NCOPTION_NO_FONT_CHANGES.html) - /// - [`NCOPTION_NO_QUIT_SIGHANDLERS`](type.NCOPTION_NO_QUIT_SIGHANDLERS.html) - /// - [`NCOPTION_NO_WINCH_SIGHANDLER`](type.NCOPTION_NO_WINCH_SIGHANDLER.html) - /// - [`NCOPTION_SUPPRESS_BANNERS`](type.NCOPTION_SUPPRESS_BANNERS.html) + /// - [`NCOPTION_INHIBIT_SETLOCALE`] + /// - [`NCOPTION_NO_ALTERNATE_SCREEN`] + /// - [`NCOPTION_NO_FONT_CHANGES`] + /// - [`NCOPTION_NO_QUIT_SIGHANDLERS`] + /// - [`NCOPTION_NO_WINCH_SIGHANDLER`] + /// - [`NCOPTION_SUPPRESS_BANNERS`] /// pub fn with_all_options( loglevel: NcLogLevel, diff --git a/rust/src/plane.rs b/rust/src/plane.rs index 2a88ba601..4a91947bc 100644 --- a/rust/src/plane.rs +++ b/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, diff --git a/rust/src/types/cell.rs b/rust/src/types/cell.rs index 9db420c7e..3f52756be 100644 --- a/rust/src/types/cell.rs +++ b/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 diff --git a/rust/src/types/channel.rs b/rust/src/types/channel.rs index 0e8bf7bfb..17d9dff20 100644 --- a/rust/src/types/channel.rs +++ b/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 diff --git a/rust/src/types/plane.rs b/rust/src/types/plane.rs index 614159940..5df5fb013 100644 --- a/rust/src/types/plane.rs +++ b/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 diff --git a/rust/src/types/terminal.rs b/rust/src/types/terminal.rs index 9cb27be43..279678d83 100644 --- a/rust/src/types/terminal.rs +++ b/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 diff --git a/rust/src/types/widgets.rs b/rust/src/types/widgets.rs index c84f6f5e7..62c685cb0 100644 --- a/rust/src/types/widgets.rs +++ b/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;