Archives
/
notcurses
mirror of https://github.com/dankamongmen/notcurses
2
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

rust: improve comments

Browse Source 
- use new syntax for doclinks
- improve some comments
- add README
pull/1128/head
joseLuís 4 years ago
parent 7ee2d98f82
commit e23cd63aac
12 changed files with 59 additions and 45 deletions
Show Stats Download Patch File Download Diff File

4
rust/README.md
Unescape Escape View File

@ -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)

9
rust/src/bindings.rs
Unescape Escape View File

@ -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"));

2
rust/src/cells.rs
Unescape Escape View File

@ -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.
///

2
rust/src/lib.rs
Unescape Escape View File

@ -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)

6
rust/src/macros.rs
Unescape Escape View File

@ -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 ) => {

12
rust/src/notcurses.rs
Unescape Escape View File

@ -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,

3
rust/src/plane.rs
Unescape Escape View File

@ -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,

6
rust/src/types/cell.rs
Unescape Escape View File

@ -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

10
rust/src/types/channel.rs
Unescape Escape View File

@ -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

16
rust/src/types/plane.rs
Unescape Escape View File

@ -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

6
rust/src/types/terminal.rs
Unescape Escape View File

@ -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

28
rust/src/types/widgets.rs
Unescape Escape View File

@ -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;

Write Preview
Loading…
Cancel
Save