From: Markus Triska <triska@metalevel.at>
Date: Sat, 16 Mar 2024 19:24:44 +0000 (+0100)
Subject: DOC: Improve descriptions to make clear what encoding(octet) means.
X-Git-Tag: v0.10.0~152^2~2
X-Git-Url: https://git.sagredo.dev/?a=commitdiff_plain;h=4ebdd97ad3a26a5f08988d02b0683c9b32bc9ec6;p=scryer-prolog.git

DOC: Improve descriptions to make clear what encoding(octet) means.

In particular, octet does *not* mean that the input is a list of
Prolog bytes in the sense of "integers between 0..255", but that the
character codes are used directly as byte values.
---

diff --git a/src/lib/crypto.pl b/src/lib/crypto.pl
index 53e3bdb9..b69ed581 100644
--- a/src/lib/crypto.pl
+++ b/src/lib/crypto.pl
@@ -217,7 +217,8 @@ crypto_random_byte(B) :- '$crypto_random_byte'(B).
 %
 %    - `encoding(+Encoding)`
 %      The default encoding is `utf8`. The alternative is `octet`, to
-%      treat the input as a list of raw bytes.
+%      use the character code of each character in Data as a byte
+%      value.
 %
 %    - `hmac(+Key)`
 %      Compute a hash-based message authentication code (HMAC) using
@@ -334,7 +335,8 @@ hash_algorithm(blake2b512).
 %      default is all zeroes.
 %    - `encoding(+Encoding)`
 %      The default encoding is `utf8`. The alternative is `octet`,
-%      to treat the input as a list of raw bytes.
+%      to use the character code of each character in Data as a byte
+%      value.
 %
 %  The `info/1`  option can be  used to  generate multiple keys  from a
 %  single  master key,  using for  example values  such as  "key" and
@@ -540,8 +542,9 @@ bytes_base64(Bytes, Base64) :-
 %  Options:
 %
 %     - `encoding(+Encoding)`
-%     Encoding to use for PlainText. Default is utf8. The alternative
-%     is octet to treat PlainText as raw bytes.
+%     Encoding to use for PlainText. The default is `utf8`. The
+%     alternative is `octet`, to use the character code of each
+%     character in PlainText as a byte value.
 %
 %     - `tag(-List)`
 %     For authenticated encryption schemes, List is unified with a
@@ -627,8 +630,9 @@ algorithm_key_iv('chacha20-poly1305', Key, IV) :-
 %  Options is a list of:
 %
 %   - `encoding(+Encoding)`
-%   Encoding to use for PlainText. The default is utf8. The
-%   alternative is octet, which is used if the data are raw bytes.
+%   Encoding to use for PlainText. The default is `utf8`. The
+%   alternative is `octet`, to obtain a list of characters where each
+%   character code corresponds to a decrypted octet of CipherText.
 %
 %   - `tag(+Tag)`
 %   For authenticated encryption schemes, the tag must be specified as
@@ -911,7 +915,8 @@ ed25519_sign(KeyPair, Data0, Signature, Options) :-
 %
 %  - `encoding(+Encoding)`
 %    The default encoding of Data is `utf8`. The alternative is `octet`,
-%    which treats Data as a list of raw bytes.
+%    to use the character code of each character in Data as a byte
+%    value.
 
 ed25519_verify(Key, Data0, Signature0, Options) :-
         must_be_octet_chars(Key, ed25519_verify/4),