File 2522-crypto-Add-new-3-tuple-error-style-to-doc.... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 2522-crypto-Add-new-3-tuple-error-style-to-doc.patch of Package erlang (Revision 6bc8bdb9448218a96809a06da74b3d6e)

Currently displaying revision 6bc8bdb9448218a96809a06da74b3d6e , Show latest

From 3489c6c569fb42c145b0bf4c127256d4b149e070 Mon Sep 17 00:00:00 2001
From: Hans Nilsson <hans@erlang.org>
Date: Fri, 18 Mar 2022 10:34:37 +0100
Subject: [PATCH 2/2] crypto: Add new 3-tuple error style to doc

---
 lib/crypto/doc/src/crypto.xml | 29 ++++++++++++++++++-----------
 1 file changed, 18 insertions(+), 11 deletions(-)

diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml
index 6a95bb2cb4..c4cde105c6 100644
--- a/lib/crypto/doc/src/crypto.xml
+++ b/lib/crypto/doc/src/crypto.xml
@@ -553,7 +553,8 @@
 <section>
 <title>Exceptions</title>
 <section>
- <title>The older style</title>
+ <title>Atoms - the older style</title>
+ <marker id="error_old"/>
 The exception <c>error:badarg</c> signifies that one or more arguments are of wrong data type,
 or are otherwise badly formed.
 
@@ -565,14 +566,15 @@
 </section>
 
 <section>
- <title>The new style</title>
+ <title>3-tuples - the new style</title>
+ <marker id="error_3tup"/>
 The exception is:
 <pre>
-Tag, C_FileInfo, Description}
+error:{Tag, C_FileInfo, Description}
 
 Tag = badarg | notsup | error
 C_FileInfo = term() % Usually only useful for the OTP maintainer
-Description = string() % Clear text or info for the OTP maintainer
+Description = string() % Clear text, sometimes only useful for the OTP maintainer
 </pre>
 
 The exception tags are:
@@ -588,7 +590,7 @@ Description = string() % Clear text or info for the OTP maintainer
 
 	<tag><c>error</c></tag>
 	<item>An error condition that should not occur, for example a memory allocation failed or
-	the underlying cryptolib returned an error code, for example "Can't initialize context, step 1".
+	the underlying cryptolib returned an error code, for example <c>"Can't initialize context, step 1"</c>.
 	Those text usually needs searching the C-code to be understood.
 	</item>
 </taglist>
@@ -615,6 +617,7 @@ end
 <name name="crypto_init" arity="3" since="OTP 22.0"/>
 <fsummary>Initializes a series of encryptions or decryptions</fsummary>
 <desc>
+	Uses the <seeerl marker="#error_3tup">3-tuple style</seeerl> for error handling.
 	Equivalent to the call
 	<seemfa marker="#crypto_init/4"><c>crypto_init(Cipher, Key, &lt;&lt;>>, FlagOrOptions)</c></seemfa>.
 	It is intended for ciphers without an IV (nounce).
@@ -626,6 +629,7 @@ end
 <name name="crypto_init" arity="4" since="OTP 22.0"/>
 <fsummary>Initializes a series of encryptions or decryptions</fsummary>
 <desc>
+	Uses the <seeerl marker="#error_3tup">3-tuple style</seeerl> for error handling.
 	
 	Initializes a series of encryptions or decryptions and creates an internal state
 	with a reference that is returned.
@@ -682,6 +686,7 @@ end
 <name name="crypto_update" arity="2" since="OTP 22.0"/>
 <fsummary>Do an actual crypto operation on a part of the full text</fsummary>
 <desc>
+	Uses the <seeerl marker="#error_3tup">3-tuple style</seeerl> for error handling.
 	
 	It does an actual crypto operation on a part of the full text. If the part is less
 	than a number of full blocks, only the full blocks (possibly none) are encrypted
@@ -701,6 +706,7 @@ end
 <name name="crypto_dyn_iv_init" arity="3" since="OTP 22.0"/>
 <fsummary>Initializes a series of encryptions or decryptions where the IV is provided later</fsummary>
 <desc>
+	Uses the <seeerl marker="#error_3tup">3-tuple style</seeerl> for error handling.
 	Initializes a series of encryptions or decryptions where the IV is provided later.
 	The actual encryption or decryption is done by
 	<seemfa marker="crypto#crypto_dyn_iv_update/3">crypto_dyn_iv_update/3</seemfa>.
@@ -715,6 +721,7 @@ end
 <name name="crypto_final" arity="1" since="OTP 23.0"/>
 <fsummary>Ends a series of encryptions or decryptions</fsummary>
 <desc>
+	Uses the <seeerl marker="#error_3tup">3-tuple style</seeerl> for error handling.
 	
 	Finalizes a series of encryptions or decryptions and delivers the final bytes of the final block.
 	The data returned from this function may be empty if no padding was enabled in
@@ -728,6 +735,7 @@ end
 <name name="crypto_get_data" arity="1" since="OTP 23.0"/>
 <fsummary>Get information about crypto states</fsummary>
 <desc>
+	Uses the <seeerl marker="#error_3tup">3-tuple style</seeerl> for error handling.
 	
 	 Returns information about the State in the argument. The information is the form of a map,
 	 which currently contains at least:
@@ -756,6 +764,7 @@ end
 <name name="crypto_dyn_iv_update" arity="3" since="OTP 22.0"/>
 <fsummary>Do an actual crypto operation on a part of the full text and the IV is supplied for each part</fsummary>
 <desc>
+	Uses the <seeerl marker="#error_3tup">3-tuple style</seeerl> for error handling.
 	
 	Do an actual crypto operation on a part of the full text and the IV is supplied for each part.
 	The <c>State</c> should be created with
@@ -768,6 +777,7 @@ end
 <name name="crypto_one_time" arity="4" since="OTP 22.0"/>
 <fsummary>Do a complete encrypt or decrypt of the full text</fsummary>
 <desc>
+	Uses the <seeerl marker="#error_3tup">3-tuple style</seeerl> for error handling.
 	As <seemfa marker="#crypto_one_time/5">crypto_one_time/5</seemfa> but for ciphers without IVs.
 </desc>
 </func>
@@ -776,6 +786,7 @@ end
 <name name="crypto_one_time" arity="5" since="OTP 22.0"/>
 <fsummary>Do a complete encrypt or decrypt of the full text</fsummary>
 <desc>
+	Uses the <seeerl marker="#error_3tup">3-tuple style</seeerl> for error handling.
 	
 	Do a complete encrypt or decrypt of the full text in the argument <c>Data</c>.
 	
@@ -793,6 +804,7 @@ end
 <name name="crypto_one_time_aead" arity="7" since="OTP 22.0"/>
 <fsummary>Do a complete encrypt or decrypt with an AEAD cipher of the full text</fsummary>
 <desc>
+	Uses the <seeerl marker="#error_3tup">3-tuple style</seeerl> for error handling.
 	
 	Do a complete encrypt or decrypt with an AEAD cipher of the full text.
 	
@@ -1050,15 +1062,10 @@ end
 <name name="generate_key" arity="3" since="OTP R16B01"/>
 <fsummary>Generates a public key of type <c>Type</c></fsummary>
 <desc>
+	Uses the <seeerl marker="#error_3tup">3-tuple style</seeerl> for error handling.
 	Generates a public key of type <c>Type</c>.
 	See also <seemfa marker="public_key:public_key#generate_key/1">public_key:generate_key/1</seemfa>.
-	May raise exception:
 
- <list type="bulleted">
- <item><c>error:badarg</c>: an argument is of wrong type or has an illegal value,</item>
-	 <item><c>error:low_entropy</c>: the random generator failed due to lack of secure "randomness",</item>
- <item><c>error:computation_failed</c>: the computation fails of another reason than <c>low_entropy</c>.</item>
- </list>
 	<note>
 	 RSA key generation is only available if the runtime was
 	 built with dirty scheduler support. Otherwise, attempting to
-- 
2.34.1

Places

File 2522-crypto-Add-new-3-tuple-error-style-to-doc.patch of Package erlang (Revision 6bc8bdb9448218a96809a06da74b3d6e)

Places