update comments on vtenc.h (API documentation)

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);