From aa0ec837863f7741adbf050b1a0bd8ffcfbf189d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Benjamin=20Gro=C3=9Fe?= Date: Sat, 4 Nov 2023 09:39:08 +0000 Subject: [PATCH] fix docs for window_size 1. Fix external link formatting. 2. Be specific about all fields possibly being zero, and the pixel fields being documented for **linux** as "unused". 3. (I am not sure about TIOCGWINSZ bing posix). 4. Specify that `window_size()` always returns an error on windows. 5. Put the detailed docs in `WindowSize`. --- src/terminal.rs | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/src/terminal.rs b/src/terminal.rs index 49f413b1..142db52d 100644 --- a/src/terminal.rs +++ b/src/terminal.rs @@ -130,13 +130,19 @@ pub fn disable_raw_mode() -> io::Result<()> { sys::disable_raw_mode() } -/// Returns the terminal size `(columns, rows)`. +/// Returns the terminal size in `(columns, rows)`. /// /// The top left cell is represented `(1, 1)`. pub fn size() -> io::Result<(u16, u16)> { sys::size() } +/// Terminal size in both `(columns, rows)` and pixel `(width, height)`. +/// +/// The returned width and height by the terminal may not be reliable or default to 0. +/// For linux, [tty_ioctl] specifically the `width` and `height` fields are documented as "unused". +/// +/// [tty_ioctl]: https://man7.org/linux/man-pages/man4/tty_ioctl.4.html #[derive(Debug)] pub struct WindowSize { pub rows: u16, @@ -145,11 +151,10 @@ pub struct WindowSize { pub height: u16, } -/// Returns the terminal size `[WindowSize]`. +/// Returns the terminal `(columns,rows)` and also pixel sizes as [WindowSize]. /// -/// The width and height in pixels may not be reliably implemented or default to 0. -/// For unix, https://man7.org/linux/man-pages/man4/tty_ioctl.4.html documents them as "unused". -/// For windows it is not implemented. +/// All fields in the struct may default to zero without returning en error. +/// On windows this **always** returns an error. pub fn window_size() -> io::Result { sys::window_size() }