hare

commit 6d4db68d30447032f5c70a4c26f48bd34de17b09
parent b22b7d393f63f85307ba5bcf6e25bdf7f144b7b7
Author: Alexey Yerin <yyp@disroot.org>
Date:   Tue, 31 Aug 2021 23:07:31 +0300

unix::tty: improve documentation a bit

* Document winsize and error types.
* Avoid using "file descriptor", use "terminal" instead. The functions
  assume to be used on a terminal, and using the former term provides
  no useful information to the end user.
* Collapse docstring of ttysize(), mostly rehomed between it and winsize
  struct.

Signed-off-by: Alexey Yerin <yyp@disroot.org>

Diffstat:
M
unix/tty/+linux/isatty.ha
 | 
2
+-
M
unix/tty/+linux/winsize.ha
 | 
3
+--
M
unix/tty/types.ha
 | 
2
++

3 files changed, 4 insertions(+), 3 deletions(-)
diff --git a/unix/tty/+linux/isatty.ha b/unix/tty/+linux/isatty.ha
@@ -2,7 +2,7 @@ use rt;
 use io;
 use os;
 
-// Returns true if the file descriptor underlying a stream is a terminal.
+// Returns whether the given stream is connected to a terminal.
 export fn isatty(stream: *io::stream) bool = {
 	let fd = match (os::streamfd(stream, true)) {
 		f: int => f,
diff --git a/unix/tty/+linux/winsize.ha b/unix/tty/+linux/winsize.ha
@@ -3,8 +3,7 @@ use io;
 use os;
 use rt;
 
-// Returns an winsize struct containing the dimensions of underlying fd of the
-// stream.
+// Returns the dimensions of underlying terminal of the stream.
 export fn winsize(tty: *io::stream) (ttysize | error) = {
 	let fd = match (os::streamfd(tty, true)) {
 		f: int => f,
diff --git a/unix/tty/types.ha b/unix/tty/types.ha
@@ -1,7 +1,9 @@
 use errors;
 
+// Any error that may occur during TTY-related tasks.
 export type error = !(errors::invalid | errors::unsupported | errors::noentry);
 
+// Structure representing dimensions of a terminal.
 export type ttysize = struct {
 	rows:    u16,
 	columns: u16,