Commit Graph

186 Commits

Author SHA1 Message Date
Jia Tan 8f23657498 liblzma: Exports lzma_mt_block_size() as an API function.
The lzma_mt_block_size() was previously just an internal function for
the multithreaded .xz encoder. It is used to provide a recommended Block
size for a given filter chain.

This function is helpful to determine the maximum Block size for the
multithreaded .xz encoder when one wants to change the filters between
blocks. Then, this determined Block size can be provided to
lzma_stream_encoder_mt() in the lzma_mt options parameter when
intializing the coder. This requires one to know all the filter chains
they are using before starting to encode (or at least the filter chain
that will need the largest Block size), but that isn't a bad limitation.
2023-05-11 23:54:44 +08:00
Jia Tan fd90e2f4c2 liblzma: Remove note from lzma_options_bcj about the ARM64 exception.
This was left in by mistake since an early version of the ARM64 filter
used a different struct for its options.
2023-03-17 01:42:28 +08:00
Jia Tan 55ba6e9300 liblzma: Add set lzma.h as the main page for Doxygen documentation.
The \mainpage command is used in the first block of comments in lzma.h.
This changes the previously nearly empty index.html to use the first
comment block in lzma.h for its contents.

lzma.h is no longer documented separately, but this is for the better
since lzma.h only defined a few macros that users do not need to use.
The individual API header files all have a disclaimer that they should
not be #included directly, so there should be no confusion on the fact
that lzma.h should be the only header used by applications.

Additionally, the note "See ../lzma.h for information about liblzma as
a whole." was removed since lzma.h is now the main page of the
generated HTML and does not have its own page anymore. So it would be
confusing in the HTML version and was only a "nice to have" when
browsing the source files.
2023-03-17 01:42:28 +08:00
Jia Tan af55191102 liblzma: Defines masks for return values from lzma_index_checks(). 2023-03-13 20:49:53 +08:00
Jia Tan f1ab1f6b33 liblzma: Clarify lzma_lzma_preset() documentation in lzma12.h.
lzma_lzma_preset() does not guarentee that the lzma_options_lzma are
usable in an encoder even if it returns false (success). If liblzma
is built with default configurations, then the options will always be
usable. However if the match finders hc3, hc4, or bt4 are disabled, then
the options may not be usable depending on the preset level requested.

The documentation was updated to reflect this complexity, since this
behavior was unclear before.
2023-03-01 21:42:31 +08:00
Jia Tan 3cf72c4bcb liblzma: Replace '\n' -> newline in filter.h documentation.
The '\n' renders as a newline when the comments are converted to html
by Doxygen.
2023-02-24 21:09:39 +08:00
Jia Tan 002006be62 liblzma: Shorten return description for two functions in filter.h.
Shorten the description for lzma_raw_encoder_memusage() and
lzma_raw_decoder_memusage().
2023-02-24 21:09:39 +08:00
Jia Tan 463d9359b8 liblzma: Reword a few lines in filter.h 2023-02-24 21:09:39 +08:00
Jia Tan 01441df92c 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.
2023-02-24 21:09:39 +08:00
Jia Tan fa9065fac5 liblzma: Adjust container.h for consistency with filter.h. 2023-02-23 20:27:59 +08:00
Jia Tan 00a721b63d liblzma: Fix small typos and reword a few things in filter.h. 2023-02-23 20:27:59 +08:00
Jia Tan 5b1c171d4f liblzma: Convert list of flags in lzma_mt to bulleted list. 2023-02-23 20:27:59 +08:00
Jia Tan dbd47622eb liblzma: Fix typo in documentation in container.h
lzma_microlzma_decoder -> lzma_microlzma_encoder
2023-02-23 20:27:59 +08:00
Jia Tan 14cd30806d liblzma: Improve documentation for container.h
Standardizing each function to always specify parameters and return
values. Also moved the parameters and return values to the end of each
function description.
2023-02-23 20:27:59 +08:00
Lasse Collin d831072cce liblzma: Very minor API doc tweaks.
Use "member" to refer to struct members as that's the term used
by the C standard.

Use lzma_options_delta.dist and such in docs so that in Doxygen's
HTML output they will link to the doc of the struct member.

Clean up a few trailing white spaces too.
2023-02-16 21:09:00 +02:00
Jia Tan f029daea39 liblzma: Adjust spacing in doc headers in bcj.h. 2023-02-17 00:54:33 +08:00
Jia Tan a5de68bac2 liblzma: Adjust documentation in bcj.h for consistent style. 2023-02-17 00:49:47 +08:00
Jia Tan efa498c13b liblzma: Rename field => member in documentation.
Also adjusted preset value => preset level.
2023-02-17 00:49:47 +08:00
Jia Tan 87c53553fa liblzma: Improve documentation for stream_flags.h
Standardizing each function to always specify parameters and return
values. Also moved the parameters and return values to the end of each
function description.

A few small things were reworded and long sentences broken up.
2023-02-16 21:04:54 +08:00
Jia Tan 13d99e75a5 liblzma: Improve documentation in lzma12.h.
All functions now explicitly specify parameter and return values.
2023-02-15 22:21:44 +08:00
Jia Tan 43ec344c86 liblzma: Improve documentation in check.h.
All functions now explicitly specify parameter and return values.
Also moved the note about SHA-256 functions not being exported to the
top of the file.
2023-02-15 00:59:16 +08:00
Jia Tan 9c71db4e88 liblzma: Improve documentation in index.h
All functions now explicitly specify parameter and return values.
2023-02-15 00:20:44 +08:00
Jia Tan 421f2f2e16 liblzma: Reword a comment in index.h. 2023-02-15 00:20:44 +08:00
Jia Tan b675394849 liblzma: Omit lzma_index_iter's internal field from Doxygen docs.
Add \private above this field and its sub-fields since it is not meant
to be modified by users.
2023-02-15 00:20:44 +08:00
Jia Tan 0c9e4fc2ad liblzma: Fix documentation for LZMA_MEMLIMIT_ERROR.
LZMA_MEMLIMIT_ERROR was missing the "<" character needed to put
documentation after a member.
2023-02-14 20:41:05 +08:00
Jia Tan 816fec125a liblzma: Improve documentation for base.h.
Standardizing each function to always specify params and return values.
Also fixed a small grammar mistake.
2023-02-14 20:41:05 +08:00
Jia Tan 862dacef1a liblzma: Add one more missing [out] annotation in vli.h 2023-02-14 00:12:34 +08:00
Jia Tan 867b08ae42 liblzma: Minor improvements to vli.h.
Added [out] annotations to parameters that are pointers and can have
their value changed. Also added a clarification to lzma_vli_is_valid.
2023-02-14 00:08:33 +08:00
Jia Tan 90d0e628ff liblzma: Add comments for macros in delta.h.
Document LZMA_DELTA_DIST_MIN and LZMA_DELTA_DIST_MAX for completeness
and to avoid Doxygen warnings.
2023-02-10 21:38:25 +08:00
Jia Tan 9255fffdb1 liblzma: Improve documentation in index_hash.h.
All functions now explicitly specify parameter and return values.
Also reworded the description of lzma_index_hash_init() for readability.
2023-02-10 21:35:23 +08:00
Jia Tan 912af91b10 liblzma: Improve documentation for version.h.
Specified parameter and return values for API functions and documented
a few more of the macros.
2023-02-04 20:11:36 +08:00
Jia Tan 54ad83c1ae liblzma: Clarify block encoder and decoder documentation.
Added a few sentences to the description for lzma_block_encoder() and
lzma_block_decoder() to highlight that the Block Header must be coded
before calling these functions.
2023-02-03 00:22:53 +08:00
Jia Tan f680e771b3 Update lzma_block documentation for lzma_block_uncomp_encode(). 2023-02-03 00:22:53 +08:00
Jia Tan 504cf4af89 liblzma: Minor edits to lzma_block header_size documentation. 2023-02-03 00:22:53 +08:00
Jia Tan 115b720fb5 liblzma: Enumerate functions that read version in lzma_block. 2023-02-03 00:22:53 +08:00
Jia Tan 85ea0979ad liblzma: Clarify comment in block.h. 2023-02-03 00:22:53 +08:00
Jia Tan 1f7ab90d9c liblzma: Improve documentation for block.h.
Standardizing each function to always specify params and return values.
Output pointer parameters are also marked with doxygen style [out] to
make it clear. Any note sections were also moved above the parameter and
return sections for consistency.
2023-02-03 00:22:53 +08:00
Jia Tan c563a4bc55 liblzma: Clarify a comment about LZMA_STR_NO_VALIDATION.
The flag description for LZMA_STR_NO_VALIDATION was previously confusing
about the treatment for filters than cannot be used with .xz format
(lzma1) without using LZMA_STR_ALL_FILTERS. Now, it is clear that
LZMA_STR_NO_VALIDATION is not a super set of LZMA_STR_ALL_FILTERS.
2023-02-01 23:39:45 +08:00
Jia Tan f35d98e206 liblzma: Fix documentation in filter.h for lzma_str_to_filters()
The previous documentation for lzma_str_to_filters() was technically
correct, but misleading. lzma_str_to_filters() returns NULL on success,
which is in practice always defined to 0. This is the same value as
LZMA_OK, but lzma_str_to_filters() does not return lzma_ret so we should
be more clear.
2023-01-24 20:48:50 +08:00
Jia Tan 9663141274 liblzma: Set documentation on all reserved fields to private.
This prevents the reserved fields from being part of the generated
Doxygen documentation.
2023-01-21 21:37:48 +08:00
Jia Tan 6fcf4671b6 liblzma: Highlight liblzma API headers should not be included directly.
This improves the generated Doxygen HTML files to better highlight
how to properly use the liblzma API header files.
2023-01-20 00:51:12 +08:00
Lasse Collin 4103a2e78a Bump version and soname for 5.5.0alpha.
5.5.0alpha won't be released, it's just to mark that
the branch is not for stable 5.4.x.

Once again there is no API/ABI stability for new features
in devel versions. The major soname won't be bumped even
if API/ABI of new features breaks between devel releases.
2023-01-02 17:20:47 +02:00
Lasse Collin b69da6d4bb Bump version to 5.4.0 and soname to 5.4.0. 2022-12-13 20:46:41 +02:00
Lasse Collin 31dbd1e5fb liblzma: Change LZMA_FILTER_ARM64 to the official Filter ID 0x0A. 2022-12-11 21:13:06 +02:00
Lasse Collin 24790f49ae Bump version number for 5.3.5beta.
This also sorts the symbol names alphabetically in liblzma_*.map.
2022-12-01 20:59:32 +02:00
Lasse Collin f9ca7d4516 liblzma: Omit zero-skipping from ARM64 filter.
It has some complicated downsides and its usefulness is more limited
than I originally thought. So this change is bad for certain very
specific situations but a generic solution that works for other
filters (and is otherwise better too) is planned anyway. And this
way 7-Zip can use the same compatible filter for the .7z format.

This is still marked as experimental with a new temporary Filter ID.
2022-12-01 18:55:00 +02:00
Lasse Collin 0c3627b518 liblzma: Don't be over-specific in lzma_str_to_filters API doc. 2022-12-01 18:12:03 +02:00
Jia Tan 0a72b9ca2f liblzma: Improve documentation for string to filter functions. 2022-11-29 22:29:15 +02:00
Lasse Collin a6e21fcede liblzma: Two fixes to lzma_str_list_filters() API docs.
Thanks to Jia Tan.
2022-11-29 22:27:42 +02:00
Lasse Collin cedeeca2ea liblzma: Add lzma_str_to_filters, _from_filters, and _list_filters.
lzma_str_to_filters() uses static error messages which makes
them not very precise. It tells the position in the string
where an error occurred though which helps quite a bit if
applications take advantage of it. Dynamic error messages can
be added later with a new flag if it seems important enough.
2022-11-28 21:54:24 +02:00