From 75913799e5eda74f0a40edbfc14d741f46aea6e5 Mon Sep 17 00:00:00 2001 From: Vicente Romero Date: Wed, 16 Feb 2022 15:50:40 +0000 Subject: [PATCH] update comments on vtenc.h (API documentation) --- vtenc.h | 46 +++++++++++++++++++++++++++++++--------------- 1 file changed, 31 insertions(+), 15 deletions(-) diff --git a/vtenc.h b/vtenc.h index 1304b73..4585ca2 100644 --- a/vtenc.h +++ b/vtenc.h @@ -49,7 +49,23 @@ void vtenc_destroy(vtenc *handler); * Configuration options. * * These constants are the available integer options that can be passed as the - * second argument to the `vtenc_config` function. + * second argument to the vtenc_config() function. + * + * VTENC_CONFIG_ALLOW_REPEATED_VALUES takes a single argument of type int. If + * non-zero, the sequence to be encoded or decoded can have repeated values. + * If the parameter is zero, the sequence is considered to be a set with no + * repeated values. + * + * VTENC_CONFIG_SKIP_FULL_SUBTREES takes a single argument of type int. If + * non-zero, full subtrees are skipped to be encoded, meaning that children + * nodes in a full subtree are not part of the encoded stream. If argument is + * zero, this functionality is disabled. + * VTENC_CONFIG_SKIP_FULL_SUBTREES is only relevant to sets, so this config + * will be ignored when VTENC_CONFIG_ALLOW_REPEATED_VALUES is set to a non-zero + * value. + * + * VTENC_CONFIG_MIN_CLUSTER_LENGTH takes a single argument of type size_t. It + * sets the minimun cluster length that is encoded. */ #define VTENC_CONFIG_ALLOW_REPEATED_VALUES 0 /* int */ #define VTENC_CONFIG_SKIP_FULL_SUBTREES 1 /* int */ @@ -64,22 +80,21 @@ int vtenc_config(vtenc *handler, int op, ...); * Functions to encode the sequence @in into the already-allocated stream of * bytes @out, using the VTEnc algorithm with the provided encoding parameters. * - * @enc: encoder. Provides encoding parameters and holds the returning state. + * @enc: encoder. Provides encoding parameters. * @in: input sequence to be encoded. * @in_len: size of @in. * @out: output stream of bytes. * @out_cap: capacity of @out / number of allocated bytes in @out. * - * In case of error, @enc->last_error_code contains a specific error code - * after calling the function. Otherwise, it has a 'VtencErrorNoError' code. + * Returns VTENC_OK if the encoding is successful. Otherwise, an error code + * will be returned (see result codes for more info). * - * Note that these functions assume that @in is a sorted sequence and they don't - * check its order. If you pass in an unsorted sequence, @enc->last_error_code - * will still have a 'VtencErrorNoError' value after calling the function, but - * the output won't correspond to the correct encoded stream for the input - * sequence. + * The output size can be obtained by calling vtenc_encoded_size() separately. * - * Return the size of the encoded output @out. + * Note that these functions assume that @in is a sorted sequence and they don't + * check its order. If you pass in an unsorted sequence, you may still get a + * VTENC_OK code, but the output won't necessarily correspond to the correct + * encoded stream for the input sequence. */ int vtenc_encode8(vtenc *enc, const uint8_t *in, size_t in_len, uint8_t *out, size_t out_cap); int vtenc_encode16(vtenc *enc, const uint16_t *in, size_t in_len, uint8_t *out, size_t out_cap); @@ -109,18 +124,19 @@ size_t vtenc_max_encoded_size64(size_t in_len); * vtenc_decode* functions. * * Functions to decode the stream of bytes @in into the already-allocated - * sequence @out, using the VTEnc algorithm with the provided decoding + * sequence @out, using the VTEnc algorithm with the provided encoding * parameters. * - * @dec: decoder. Provides decoding parameters and holds the returning state. + * @dec: decoder. Provides encoding parameters. * @in: input stream of bytes to be decoded. * @in_len: size of @in. * @out: output sequence. * @out_len: size of @out. * - * In case of failure, @dec->last_error_code contains the error code after - * calling the function. If the function didn't fail, it holds a - * 'VtencErrorNoError' value. + * Returns VTENC_OK when the decoding is successful or an error code otherwise. + * + * Note that the size of the output (@out_len) needs to be known to call a + * vtenc_decode* function. */ int vtenc_decode8(vtenc *dec, const uint8_t *in, size_t in_len, uint8_t *out, size_t out_len); int vtenc_decode16(vtenc *dec, const uint8_t *in, size_t in_len, uint16_t *out, size_t out_len);