commit e59ae9bf958f82d34a2897172774fdff94523785
parent 5101d99b1600acebd796c730bb4ef2d3ff627fb3
Author: Umar Getagazov <umar@handlerug.me>
Date: Thu, 26 May 2022 15:56:46 +0000
all: various documentation fixes
Fixes some of the unresolved references and incorrect documentation.
Signed-off-by: Umar Getagazov <umar@handlerug.me>
Diffstat:
8 files changed, 26 insertions(+), 25 deletions(-)
diff --git a/crypto/blowfish/blowfish.ha b/crypto/blowfish/blowfish.ha
@@ -20,9 +20,9 @@ export type state = struct {
};
// Initializes a new Blowfish cipher. The user should must call [[init]] or
-// [[init_salt]] prior to use, then may use [[cipher::encrypt]] et al. The user
-// must call [[finish]] when they are done using the stream to securely erase
-// secret information stored in the stream state.
+// [[init_salt]] prior to use, then may use [[crypto::cipher::encrypt]] et al.
+// The user must call [[finish]] when they are done using the stream to securely
+// erase secret information stored in the stream state.
export fn new() state = {
return state {
blocksz = BLOCKSIZE,
diff --git a/crypto/chacha/README b/crypto/chacha/README
@@ -1,12 +1,13 @@
crypto::chacha provides an implementation of the Chacha20 and XChacha20 stream
ciphers.
-Use [[chacha20]] to create a [[cipher::xorstream]] and either [[chacha20_init]]
-or [[xchacha20_init]] to set the handle, key and nonce of the appropriate size,
-[[NONCESIZE]] for chacha20 or [[XNONCESIZE]] for XChacha20. After calling the
-appropriate init function, [[io::write]] may be used to encrypt blocks to the
-handle or [[io::read]] to decrypt blocks from the handle. The stream must be
-closed with [[io::close]] to wipe sensitive data from memory.
+Use [[chacha20]] to create a [[crypto::cipher::xorstream]] and either
+[[chacha20_init]] or [[xchacha20_init]] to set the handle, key and nonce of the
+appropriate size, [[NONCESIZE]] for chacha20 or [[XNONCESIZE]] for XChacha20.
+After calling the appropriate init function, [[io::write]] may be used to
+encrypt blocks to the handle or [[io::read]] to decrypt blocks from the handle.
+The stream must be closed with [[io::close]] to wipe sensitive data from
+memory.
Writing blocks of length [[BLOCKSIZE]] is not required. However, seeking the
key stream with [[setctr]] only operates in units of [[BLOCKSIZE]].
diff --git a/crypto/chacha/chacha20.ha b/crypto/chacha/chacha20.ha
@@ -21,7 +21,8 @@ export def BLOCKSIZE: size = 64;
def ROUNDS: size = 20;
const magic: [4]u32 = [0x61707865, 0x3320646e, 0x79622d32, 0x6b206574];
-// A ChaCha20 or XChaCha20 [[cipher::xorstream]] depending on intialisation.
+// A ChaCha20 or XChaCha20 [[crypto::cipher::xorstream]] depending on
+// intialisation.
export type stream = struct {
cipher::xorstream,
state: [16]u32,
diff --git a/datetime/arithmetic.ha b/datetime/arithmetic.ha
@@ -50,16 +50,16 @@ export type unit = enum int {
// Returns true if two [[datetime]]s are equivalent.
//
-// Equivalence means they represent the same moment in time,
-// regardless of their [[locality]] or observed chronological values.
+// Equivalence means they represent the same moment in time, regardless of their
+// locality or observed chronological values.
export fn eq(a: datetime, b: datetime) bool = {
return a.date == b.date && a.time == b.time;
};
// Returns true if [[datetime]] "a" succeeds [[datetime]] "b".
//
-// Temporal order is evaluated in a universal frame of reference,
-// regardless of their [[locality]] or observed chronological values.
+// Temporal order is evaluated in a universal frame of reference, regardless of
+// their locality or observed chronological values.
export fn after(a: datetime, b: datetime) bool = {
return !eq(a, b) &&
(a.date > b.date || a.date == b.date && a.time > b.time);
@@ -67,8 +67,8 @@ export fn after(a: datetime, b: datetime) bool = {
// Returns true if [[datetime]] "a" precedes [[datetime]] "b".
//
-// Temporal order is evaluated in a universal frame of reference,
-// regardless of their [[locality]] or observed chronological values.
+// Temporal order is evaluated in a universal frame of reference, regardless of
+// their locality or observed chronological values.
export fn before(a: datetime, b: datetime) bool = {
return !eq(a, b) && !after(a, b);
};
diff --git a/hare/unparse/type.ha b/hare/unparse/type.ha
@@ -208,7 +208,7 @@ fn struct_union_type(
fn multiline_comment(s: str) bool =
strings::byteindex(s, '\n') as size != len(s) - 1;
-// Unparses an [[ast::_type]].
+// Unparses a [[hare::ast::_type]].
export fn _type(
out: io::handle,
indent: size,
diff --git a/linux/timerfd/timerfd.ha b/linux/timerfd/timerfd.ha
@@ -91,8 +91,8 @@ export fn unset(
};
// Reading from the timerfd returns the number of time the timer expired. This
-// call can be blocking or not depending on the flags passed to [[timerfd_create]].
-// Reading from a blocking unset timerfd will block forever.
+// call can be blocking or not depending on the flags passed to [[new]]. Reading
+// from a blocking unset timerfd will block forever.
export fn read(
t: io::file
) (u64 | errors::error) = {
diff --git a/unix/+linux/pipe.ha b/unix/+linux/pipe.ha
@@ -4,8 +4,8 @@ use errors;
use io;
use rt;
-// Flags to use for the [[io::file]]s returned by [[pipe]]
-// Only NOCLOEXEC and NONBLOCK are guaranteed to be available.
+// Flags to use for the [[io::file]]s returned by [[pipe]]. Only NOCLOEXEC and
+// NONBLOCK are guaranteed to be available.
export type pipe_flag = enum {
NOCLOEXEC = rt::O_CLOEXEC,
DIRECT = rt::O_DIRECT,
@@ -13,9 +13,8 @@ export type pipe_flag = enum {
};
// Create a pair of two linked [[io::file]]s, such that any data written to the
-// second [[io::file]] may be read from the first. If no [[pipe_flag]]s are
-// provided, [[pipe_flag::CLOEXEC]] is used. If you pass your own flags, it is
-// recommended that you add it unless you know that you don't want it.
+// second [[io::file]] may be read from the first. If you pass your own flags,
+// it is recommended that you add it unless you know that you don't want it.
export fn pipe(flags: pipe_flag...) ((io::file, io::file) | errors::error) = {
let fds: [2]int = [0...];
let flag: pipe_flag = 0;
diff --git a/unix/signal/+linux.ha b/unix/signal/+linux.ha
@@ -86,7 +86,7 @@ export fn getprocmask() sigset = {
return old;
};
-// Defines the modes of operation for [[procmask]].
+// Defines the modes of operation for [[setprocmask]].
export type how = enum int {
// Adds the given set of signals to the current mask.
BLOCK = rt::SIG_BLOCK,
