liblzma: Improve documentation in filter.h.

All functions now explicitly specify parameter and return values.
The notes and code annotations were moved before the parameter and
return value descriptions for consistency.

Also, the description above lzma_filter_encoder_is_supported() about
not being able to list available filters was removed since
lzma_str_list_filters() will do this.

1 files changed, 143 insertions, 83 deletions

diff --git a/src/liblzma/api/lzma/filter.h b/src/liblzma/api/lzma/filter.h
index 584ea463..e76daa19 100644
--- a/src/liblzma/api/lzma/filter.h
+++ b/src/liblzma/api/lzma/filter.h
@@ -69,12 +69,12 @@ typedef struct {
 /**
  * \brief       Test if the given Filter ID is supported for encoding
  *
- * Return true if the give Filter ID is supported for encoding by this
- * liblzma build. Otherwise false is returned.
+ * \param       id      Filter ID
  *
- * There is no way to list which filters are available in this particular
- * liblzma version and build. It would be useless, because the application
- * couldn't know what kind of options the filter would need.
+ * \return      lzma_bool:
+ *              - true if the Filter ID is supported for encoding by this
+ *                liblzma build.
+  *             - false otherwise.
  */
 extern LZMA_API(lzma_bool) lzma_filter_encoder_is_supported(lzma_vli id)
 		lzma_nothrow lzma_attr_const;
@@ -83,8 +83,12 @@ extern LZMA_API(lzma_bool) lzma_filter_encoder_is_supported(lzma_vli id)
 /**
  * \brief       Test if the given Filter ID is supported for decoding
  *
- * Return true if the give Filter ID is supported for decoding by this
- * liblzma build. Otherwise false is returned.
+ * \param       id      Filter ID
+ *
+ * \return      lzma_bool:
+ *              - true if the Filter ID is supported for decoding by this
+ *                liblzma build.
+ *              - false otherwise.
  */
 extern LZMA_API(lzma_bool) lzma_filter_decoder_is_supported(lzma_vli id)
 		lzma_nothrow lzma_attr_const;
@@ -113,7 +117,14 @@ extern LZMA_API(lzma_bool) lzma_filter_decoder_is_supported(lzma_vli id)
  * array and leave its contents in an undefined state if an error occurs.
  * liblzma 5.2.7 and newer only modify the dest array when returning LZMA_OK.
  *
- * \return      - LZMA_OK
+ * \param       src         Array of filters terminated with
+ *                          .id == LZMA_VLI_UNKNOWN.
+ * \param[out]  dest        Destination filter array
+ * \param       allocator   lzma_allocator for custom allocator functions.
+ *                          Set to NULL to use malloc() and free().
+ *
+ * \return      Possible lzma_ret values:
+ *              - LZMA_OK
  *              - LZMA_MEM_ERROR
  *              - LZMA_OPTIONS_ERROR: Unsupported Filter ID and its options
  *                is not NULL.
@@ -140,6 +151,11 @@ extern LZMA_API(lzma_ret) lzma_filters_copy(
  *
  * If filters is NULL, this does nothing but remember that this never frees
  * the filters array itself.
+ *
+ * \param       filters     Array of filters terminated with
+ *                          .id == LZMA_VLI_UNKNOWN.
+ * \param       allocator   lzma_allocator for custom allocator functions.
+ *                          Set to NULL to use malloc() and free().
  */
 extern LZMA_API(void) lzma_filters_free(
 		lzma_filter *filters, const lzma_allocator *allocator)
@@ -189,14 +205,16 @@ extern LZMA_API(uint64_t) lzma_raw_decoder_memusage(const lzma_filter *filters)
  *
  * This function may be useful when implementing custom file formats.
  *
- * \param       strm    Pointer to properly prepared lzma_stream
- * \param       filters Array of lzma_filter structures. The end of the
- *                      array must be marked with .id = LZMA_VLI_UNKNOWN.
- *
  * The `action' with lzma_code() can be LZMA_RUN, LZMA_SYNC_FLUSH (if the
  * filter chain supports it), or LZMA_FINISH.
  *
- * \return      - LZMA_OK
+ * \param       strm      Pointer to lzma_stream that is at least
+ *                        initialized with LZMA_STREAM_INIT.
+ * \param       filters   Array of filters terminated with
+ *                        .id == LZMA_VLI_UNKNOWN.
+ *
+ * \return      Possible lzma_ret values:
+ *              - LZMA_OK
  *              - LZMA_MEM_ERROR
  *              - LZMA_OPTIONS_ERROR
  *              - LZMA_PROG_ERROR
@@ -214,7 +232,13 @@ extern LZMA_API(lzma_ret) lzma_raw_encoder(
  * The `action' with lzma_code() can be LZMA_RUN or LZMA_FINISH. Using
  * LZMA_FINISH is not required, it is supported just for convenience.
  *
- * \return      - LZMA_OK
+ * \param       strm      Pointer to lzma_stream that is at least
+ *                        initialized with LZMA_STREAM_INIT.
+ * \param       filters   Array of filters terminated with
+ *                        .id == LZMA_VLI_UNKNOWN.
+ *
+ * \return      Possible lzma_ret values:
+ *              - LZMA_OK
  *              - LZMA_MEM_ERROR
  *              - LZMA_OPTIONS_ERROR
  *              - LZMA_PROG_ERROR
@@ -250,7 +274,13 @@ extern LZMA_API(lzma_ret) lzma_raw_decoder(
  * as if LZMA_FULL_FLUSH (Stream encoders) or LZMA_SYNC_FLUSH (Raw or Block
  * encoder) had been used right before calling this function.
  *
- * \return      - LZMA_OK
+ * \param       strm      Pointer to lzma_stream that is at least
+ *                        initialized with LZMA_STREAM_INIT.
+ * \param       filters   Array of filters terminated with
+ *                        .id == LZMA_VLI_UNKNOWN.
+ *
+ * \return      Possible lzma_ret values:
+ *              - LZMA_OK
  *              - LZMA_MEM_ERROR
  *              - LZMA_MEMLIMIT_ERROR
  *              - LZMA_OPTIONS_ERROR
@@ -263,29 +293,30 @@ extern LZMA_API(lzma_ret) lzma_filters_update(
 /**
  * \brief       Single-call raw encoder
  *
- * \param       filters     Array of lzma_filter structures. The end of the
- *                          array must be marked with .id = LZMA_VLI_UNKNOWN.
+ * \note        There is no function to calculate how big output buffer
+ *              would surely be big enough. (lzma_stream_buffer_bound()
+ *              works only for lzma_stream_buffer_encode(); raw encoder
+ *              won't necessarily meet that bound.)
+ *
+ * \param       filters     Array of filters terminated with
+ *                          .id == LZMA_VLI_UNKNOWN.
  * \param       allocator   lzma_allocator for custom allocator functions.
  *                          Set to NULL to use malloc() and free().
  * \param       in          Beginning of the input buffer
  * \param       in_size     Size of the input buffer
- * \param       out         Beginning of the output buffer
- * \param       out_pos     The next byte will be written to out[*out_pos].
+ * \param[out]  out         Beginning of the output buffer
+ * \param[out]  out_pos     The next byte will be written to out[*out_pos].
  *                          *out_pos is updated only if encoding succeeds.
  * \param       out_size    Size of the out buffer; the first byte into
  *                          which no data is written to is out[out_size].
  *
- * \return      - LZMA_OK: Encoding was successful.
+ * \return      Possible lzma_ret values:
+ *              - LZMA_OK: Encoding was successful.
  *              - LZMA_BUF_ERROR: Not enough output buffer space.
  *              - LZMA_OPTIONS_ERROR
  *              - LZMA_MEM_ERROR
  *              - LZMA_DATA_ERROR
  *              - LZMA_PROG_ERROR
- *
- * \note        There is no function to calculate how big output buffer
- *              would surely be big enough. (lzma_stream_buffer_bound()
- *              works only for lzma_stream_buffer_encode(); raw encoder
- *              won't necessarily meet that bound.)
  */
 extern LZMA_API(lzma_ret) lzma_raw_buffer_encode(
 		const lzma_filter *filters, const lzma_allocator *allocator,
@@ -296,8 +327,8 @@ extern LZMA_API(lzma_ret) lzma_raw_buffer_encode(
 /**
  * \brief       Single-call raw decoder
  *
- * \param       filters     Array of lzma_filter structures. The end of the
- *                          array must be marked with .id = LZMA_VLI_UNKNOWN.
+ * \param       filters     Array of filters terminated with
+ *                          .id == LZMA_VLI_UNKNOWN.
  * \param       allocator   lzma_allocator for custom allocator functions.
  *                          Set to NULL to use malloc() and free().
  * \param       in          Beginning of the input buffer
@@ -305,11 +336,19 @@ extern LZMA_API(lzma_ret) lzma_raw_buffer_encode(
  *                          *in_pos is updated only if decoding succeeds.
  * \param       in_size     Size of the input buffer; the first byte that
  *                          won't be read is in[in_size].
- * \param       out         Beginning of the output buffer
- * \param       out_pos     The next byte will be written to out[*out_pos].
+ * \param[out]  out         Beginning of the output buffer
+ * \param[out]  out_pos     The next byte will be written to out[*out_pos].
  *                          *out_pos is updated only if encoding succeeds.
  * \param       out_size    Size of the out buffer; the first byte into
  *                          which no data is written to is out[out_size].
+ *
+ * \return      Possible lzma_ret values:
+ *              - LZMA_OK: Decoding was successful.
+ *              - LZMA_BUF_ERROR: Not enough output buffer space.
+ *              - LZMA_OPTIONS_ERROR
+ *              - LZMA_MEM_ERROR
+ *              - LZMA_DATA_ERROR
+ *              - LZMA_PROG_ERROR
  */
 extern LZMA_API(lzma_ret) lzma_raw_buffer_decode(
 		const lzma_filter *filters, const lzma_allocator *allocator,
@@ -323,18 +362,19 @@ extern LZMA_API(lzma_ret) lzma_raw_buffer_decode(
  * This function may be useful when implementing custom file formats
  * using the raw encoder and decoder.
  *
- * \param       size    Pointer to uint32_t to hold the size of the properties
+ * \note        This function validates the Filter ID, but does not
+ *              necessarily validate the options. Thus, it is possible
+ *              that this returns LZMA_OK while the following call to
+ *              lzma_properties_encode() returns LZMA_OPTIONS_ERROR.
+ *
+ * \param[out]  size    Pointer to uint32_t to hold the size of the properties
  * \param       filter  Filter ID and options (the size of the properties may
  *                      vary depending on the options)
  *
- * \return      - LZMA_OK
+ * \return      Possible lzma_ret values:
+ *              - LZMA_OK
  *              - LZMA_OPTIONS_ERROR
  *              - LZMA_PROG_ERROR
- *
- * \note        This function validates the Filter ID, but does not
- *              necessarily validate the options. Thus, it is possible
- *              that this returns LZMA_OK while the following call to
- *              lzma_properties_encode() returns LZMA_OPTIONS_ERROR.
  */
 extern LZMA_API(lzma_ret) lzma_properties_size(
 		uint32_t *size, const lzma_filter *filter) lzma_nothrow;
@@ -343,15 +383,6 @@ extern LZMA_API(lzma_ret) lzma_properties_size(
 /**
  * \brief       Encode the Filter Properties field
  *
- * \param       filter  Filter ID and options
- * \param       props   Buffer to hold the encoded options. The size of
- *                      buffer must have been already determined with
- *                      lzma_properties_size().
- *
- * \return      - LZMA_OK
- *              - LZMA_OPTIONS_ERROR
- *              - LZMA_PROG_ERROR
- *
  * \note        Even this function won't validate more options than actually
  *              necessary. Thus, it is possible that encoding the properties
  *              succeeds but using the same options to initialize the encoder
@@ -361,6 +392,15 @@ extern LZMA_API(lzma_ret) lzma_properties_size(
  *              of the Filter Properties field is zero, calling
  *              lzma_properties_encode() is not required, but it
  *              won't do any harm either.
+ *
+ * \param       filter  Filter ID and options
+ * \param[out]  props   Buffer to hold the encoded options. The size of
+ *                      the buffer must have been already determined with
+ *                      lzma_properties_size().
+ *
+ * \return      Possible lzma_ret values:
+ *              - LZMA_OK
+ *              - LZMA_PROG_ERROR
  */
 extern LZMA_API(lzma_ret) lzma_properties_encode(
 		const lzma_filter *filter, uint8_t *props) lzma_nothrow;
@@ -376,15 +416,16 @@ extern LZMA_API(lzma_ret) lzma_properties_encode(
  *                          it's application's responsibility to free it when
  *                          appropriate. filter->options is set to NULL if
  *                          there are no properties or if an error occurs.
- * \param       allocator   Custom memory allocator used to allocate the
- *                          options. Set to NULL to use the default malloc(),
+ * \param       allocator   lzma_allocator for custom allocator functions.
+ *                          Set to NULL to use malloc() and free().
  *                          and in case of an error, also free().
  * \param       props       Input buffer containing the properties.
  * \param       props_size  Size of the properties. This must be the exact
  *                          size; giving too much or too little input will
  *                          return LZMA_OPTIONS_ERROR.
  *
- * \return      - LZMA_OK
+ * \return      Possible lzma_ret values:
+ *              - LZMA_OK
  *              - LZMA_OPTIONS_ERROR
  *              - LZMA_MEM_ERROR
  */
@@ -399,18 +440,19 @@ extern LZMA_API(lzma_ret) lzma_properties_decode(
  * Knowing the size of Filter Flags is useful to know when allocating
  * memory to hold the encoded Filter Flags.
  *
- * \param       size    Pointer to integer to hold the calculated size
+ * \note        If you need to calculate size of List of Filter Flags,
+ *              you need to loop over every lzma_filter entry.
+ *
+ * \param[out]  size    Pointer to integer to hold the calculated size
  * \param       filter  Filter ID and associated options whose encoded
  *                      size is to be calculated
  *
- * \return      - LZMA_OK: *size set successfully. Note that this doesn't
+ * \return      Possible lzma_ret values:
+ *              - LZMA_OK: *size set successfully. Note that this doesn't
  *                guarantee that filter->options is valid, thus
  *                lzma_filter_flags_encode() may still fail.
  *              - LZMA_OPTIONS_ERROR: Unknown Filter ID or unsupported options.
  *              - LZMA_PROG_ERROR: Invalid options
- *
- * \note        If you need to calculate size of List of Filter Flags,
- *              you need to loop over every lzma_filter entry.
  */
 extern LZMA_API(lzma_ret) lzma_filter_flags_size(
 		uint32_t *size, const lzma_filter *filter)
@@ -424,12 +466,13 @@ extern LZMA_API(lzma_ret) lzma_filter_flags_size(
  * This is due to how this function is used internally by liblzma.
  *
  * \param       filter      Filter ID and options to be encoded
- * \param       out         Beginning of the output buffer
- * \param       out_pos     out[*out_pos] is the next write position. This
+ * \param[out]  out         Beginning of the output buffer
+ * \param[out]  out_pos     out[*out_pos] is the next write position. This
  *                          is updated by the encoder.
  * \param       out_size    out[out_size] is the first byte to not write.
  *
- * \return      - LZMA_OK: Encoding was successful.
+ * \return      Possible lzma_ret values:
+ *              - LZMA_OK: Encoding was successful.
  *              - LZMA_OPTIONS_ERROR: Invalid or unsupported options.
  *              - LZMA_PROG_ERROR: Invalid options or not enough output
  *                buffer space (you should have checked it with
@@ -444,11 +487,26 @@ extern LZMA_API(lzma_ret) lzma_filter_flags_encode(const lzma_filter *filter,
  * \brief       Decode Filter Flags from given buffer
  *
  * The decoded result is stored into *filter. The old value of
- * filter->options is not free()d.
+ * filter->options is not free()d. If anything other than LZMA_OK
+ * is returned, filter->options is set to NULL.
+ *
+ * \param[out]  filter      Destination filter. The decoded Filter ID will
+ *                          be stored in filter->id. If options are needed
+ *                          they will be allocated and the pointer will be
+ *                          stored in filter->options.
+ * \param       allocator   lzma_allocator for custom allocator functions.
+ *                          Set to NULL to use malloc() and free().
+ * \param       in          Beginning of the input buffer
+ * \param[out]  in_pos      The next byte will be read from in[*in_pos].
+ *                          *in_pos is updated only if decoding succeeds.
+ * \param       in_size     Size of the input buffer; the first byte that
+ *                          won't be read is in[in_size].
  *
- * \return      - LZMA_OK
+ * \return      Possible lzma_ret values:
+ *              - LZMA_OK
  *              - LZMA_OPTIONS_ERROR
  *              - LZMA_MEM_ERROR
+ *              - LZMA_DATA_ERROR
  *              - LZMA_PROG_ERROR
  */
 extern LZMA_API(lzma_ret) lzma_filter_flags_decode(
@@ -575,18 +633,36 @@ extern LZMA_API(lzma_ret) lzma_filter_flags_decode(
  * lzma_str_list_filters(). See the xz man page for the description
  * of filter names and options.
  *
+ * For command line applications, below is an example how an error message
+ * can be displayed. Note the use of an empty string for the field width.
+ * If "^" was used there it would create an off-by-one error except at
+ * the very beginning of the line.
+ *
+ * \code{.c}
+ * const char *str = ...; // From user
+ * lzma_filter filters[LZMA_FILTERS_MAX + 1];
+ * int pos;
+ * const char *msg = lzma_str_to_filters(str, &pos, filters, 0, NULL);
+ * if (msg != NULL) {
+ *     printf("%s: Error in XZ compression options:\n", argv[0]);
+ *     printf("%s: %s\n", argv[0], str);
+ *     printf("%s: %*s^\n", argv[0], errpos, "");
+ *     printf("%s: %s\n", argv[0], msg);
+ * }
+ * \endcode
+ *
  * \param       str         User-supplied string describing a preset or
  *                          a filter chain. If a default value is needed and
  *                          you don't know what would be good, use "6" since
  *                          that is the default preset in xz too.
- * \param       error_pos   If this isn't NULL, this value will be set on
+ * \param[out]  error_pos   If this isn't NULL, this value will be set on
  *                          both success and on all errors. This tells the
  *                          location of the error in the string. This is
  *                          an int to make it straightforward to use this
  *                          as printf() field width. The value is guaranteed
  *                          to be in the range [0, INT_MAX] even if strlen(str)
  *                          somehow was greater than INT_MAX.
- * \param       filters     An array of lzma_filter structures. There must
+ * \param[out]  filters     An array of lzma_filter structures. There must
  *                          be LZMA_FILTERS_MAX + 1 (that is, five) elements
  *                          in the array. The old contents are ignored so it
  *                          doesn't need to be initialized. This array is
@@ -602,24 +678,6 @@ extern LZMA_API(lzma_ret) lzma_filter_flags_decode(
  * \return      On success, NULL is returned. On error, a statically-allocated
  *              error message is returned which together with the error_pos
  *              should give some idea what is wrong.
- *
- * For command line applications, below is an example how an error message
- * can be displayed. Note the use of an empty string for the field width.
- * If "^" was used there it would create an off-by-one error except at
- * the very beginning of the line.
- *
- * \code{.c}
- * const char *str = ...; // From user
- * lzma_filter filters[LZMA_FILTERS_MAX + 1];
- * int pos;
- * const char *msg = lzma_str_to_filters(str, &pos, filters, 0, NULL);
- * if (msg != NULL) {
- *     printf("%s: Error in XZ compression options:\n", argv[0]);
- *     printf("%s: %s\n", argv[0], str);
- *     printf("%s: %*s^\n", argv[0], errpos, "");
- *     printf("%s: %s\n", argv[0], msg);
- * }
- * \endcode
  */
 extern LZMA_API(const char *) lzma_str_to_filters(
 		const char *str, int *error_pos, lzma_filter *filters,
@@ -648,19 +706,20 @@ extern LZMA_API(const char *) lzma_str_to_filters(
  * specify "6" to lzma_str_to_filters() then lzma_str_from_filters()
  * will produce a string containing "lzma2".
  *
- * \param       str         On success *str will be set to point to an
+ * \param[out]  str         On success *str will be set to point to an
  *                          allocated string describing the given filter
  *                          chain. Old value is ignored. On error *str is
  *                          always set to NULL.
- * \param       filters     Array of 1-4 filters and a terminating element
- *                          with .id = LZMA_VLI_UNKNOWN.
+ * \param       filters     Array of filters terminated with
+ *                          .id == LZMA_VLI_UNKNOWN.
  * \param       flags       Bitwise-or of zero or more of the flags
  *                          LZMA_STR_ENCODER, LZMA_STR_DECODER,
  *                          LZMA_STR_GETOPT_LONG, and LZMA_STR_NO_SPACES.
  * \param       allocator   lzma_allocator for custom allocator functions.
  *                          Set to NULL to use malloc() and free().
  *
- * \return      - LZMA_OK
+ * \return      Possible lzma_ret values:
+ *              - LZMA_OK
  *              - LZMA_OPTIONS_ERROR: Empty filter chain
  *                (filters[0].id == LZMA_VLI_UNKNOWN) or the filter chain
  *                includes a Filter ID that is not supported by this function.
@@ -705,7 +764,8 @@ extern LZMA_API(lzma_ret) lzma_str_from_filters(
  * \param       allocator   lzma_allocator for custom allocator functions.
  *                          Set to NULL to use malloc() and free().
  *
- * \return      - LZMA_OK
+ * \return      Possible lzma_ret values:
+ *              - LZMA_OK
  *              - LZMA_OPTIONS_ERROR: Unsupported filter_id or flags
  *              - LZMA_MEM_ERROR
  *              - LZMA_PROG_ERROR