From 52a3273d8cf2d50729d123e399c41a3c53de5042 Mon Sep 17 00:00:00 2001 From: Project Nayuki Date: Fri, 3 Dec 2021 06:05:20 +0000 Subject: [PATCH] Updated documentation comments for QrCode::{encode_text(),encode_binary()} in Rust-no-heap and C ports. --- c/qrcodegen.h | 4 ++-- rust-no-heap/src/lib.rs | 23 +++++++++++------------ 2 files changed, 13 insertions(+), 14 deletions(-) diff --git a/c/qrcodegen.h b/c/qrcodegen.h index 922f764..c0e82af 100644 --- a/c/qrcodegen.h +++ b/c/qrcodegen.h @@ -148,7 +148,7 @@ struct qrcodegen_Segment { /*---- Functions (high level) to generate QR Codes ----*/ /* - * Encodes the given text string to a QR Code, returning true if encoding succeeded. + * Encodes the given text string to a QR Code, returning true if successful. * If the data is too long to fit in any version in the given range * at the given ECC level, then false is returned. * - The input text must be encoded in UTF-8 and contain no NULs. @@ -179,7 +179,7 @@ bool qrcodegen_encodeText(const char *text, uint8_t tempBuffer[], uint8_t qrcode /* - * Encodes the given binary data to a QR Code, returning true if encoding succeeded. + * Encodes the given binary data to a QR Code, returning true if successful. * If the data is too long to fit in any version in the given range * at the given ECC level, then false is returned. * - The variables ecl and mask must correspond to enum constant values. diff --git a/rust-no-heap/src/lib.rs b/rust-no-heap/src/lib.rs index bef9a5f..59a2b96 100644 --- a/rust-no-heap/src/lib.rs +++ b/rust-no-heap/src/lib.rs @@ -131,7 +131,9 @@ impl<'a> QrCode<'a> { /*---- Static factory functions (high level) ----*/ - /// Returns a QR Code representing the given Unicode text string with the given encoding parameters. + /// Encodes the given text string to a QR Code, returning a wrapped `QrCode` if successful. + /// If the data is too long to fit in any version in the given range + /// at the given ECC level, then `Err` is returned. /// /// The smallest possible QR Code version within the given range is automatically /// chosen for the output. Iff boostecl is `true`, then the ECC level of the result @@ -148,6 +150,9 @@ impl<'a> QrCode<'a> { /// because the function always writes before reading. /// - After the function returns, both slices have no guarantee on what values are stored. /// + /// If successful, the resulting QR Code may use numeric, + /// alphanumeric, or byte mode to encode the text. + /// /// In the most optimistic case, a QR Code at version 40 with low ECC /// can hold any UTF-8 string up to 2953 bytes, or any alphanumeric string /// up to 4296 characters, or any digit string up to 7089 characters. @@ -155,11 +160,6 @@ impl<'a> QrCode<'a> { /// /// Please consult the QR Code specification for information on /// data capacities per version, ECC level, and text encoding mode. - /// - /// If successful, the resulting QR Code may use numeric, alphanumeric, or byte mode to encode the text. - /// - /// Returns a wrapped `QrCode` if successful, or `Err` if the - /// data is too long to fit in any version at the given ECC level. pub fn encode_text<'b>(text: &str, tempbuffer: &'b mut [u8], mut outbuffer: &'a mut [u8], ecl: QrCodeEcc, minversion: Version, maxversion: Version, mask: Option, boostecl: bool) -> Result,DataTooLong> { @@ -188,7 +188,9 @@ impl<'a> QrCode<'a> { } - /// Returns a QR Code representing the given binary data with the given encoding parameters. + /// Encodes the given binary data to a QR Code, returning a wrapped `QrCode` if successful. + /// If the data is too long to fit in any version in the given range + /// at the given ECC level, then `Err` is returned. /// /// About the slices, letting len = maxversion.buffer_len(): /// - Before calling the function: @@ -201,16 +203,13 @@ impl<'a> QrCode<'a> { /// can be arbitrary because the function always writes before reading. /// - After the function returns, both slices have no guarantee on what values are stored. /// + /// If successful, the resulting QR Code will use byte mode to encode the data. + /// /// In the most optimistic case, a QR Code at version 40 with low ECC can hold any byte /// sequence up to length 2953. This is the hard upper limit of the QR Code standard. /// /// Please consult the QR Code specification for information on /// data capacities per version, ECC level, and text encoding mode. - /// - /// If successful, the resulting QR Code will use byte mode to encode the data. - /// - /// Returns a wrapped `QrCode` if successful, or `Err` if the - /// data is too long to fit in any version at the given ECC level. pub fn encode_binary<'b>(dataandtempbuffer: &'b mut [u8], datalen: usize, mut outbuffer: &'a mut [u8], ecl: QrCodeEcc, minversion: Version, maxversion: Version, mask: Option, boostecl: bool) -> Result,DataTooLong> {