From 72fe9619ad4e90c463af3ec6f6bd33e972c0598a Mon Sep 17 00:00:00 2001 From: razetime Date: Mon, 31 Oct 2022 15:15:32 +0530 Subject: [PATCH] bzip3: add full docs, fix lint problems --- extra/compression/bzip3/bzip3-docs.factor | 12 ++--- extra/compression/bzip3/ffi/ffi-docs.factor | 60 +++++++-------------- 2 files changed, 26 insertions(+), 46 deletions(-) diff --git a/extra/compression/bzip3/bzip3-docs.factor b/extra/compression/bzip3/bzip3-docs.factor index 0cc84b5656..9ed73ea6f1 100644 --- a/extra/compression/bzip3/bzip3-docs.factor +++ b/extra/compression/bzip3/bzip3-docs.factor @@ -1,15 +1,15 @@ ! Copyright (C) 2022 Raghu Ranganathan. ! See http://factorcode.org/license.txt for BSD license. -USING: byte-arrays help.markup help.syntax kernel strings ; +USING: byte-arrays help.markup help.syntax kernel multiline strings ; IN: compression.bzip3 HELP: compress -{ $values byte-array: byte-array block-size/f: { $maybe "integer" } byte-array: byte-array } -{ $description Takes a { $link "byte-array" } and block size, and pushes a compressed byte array from bzip3. } ; +{ $values byte-array: byte-array block-size/f: { $maybe "integer" } byte-array': byte-array } +{ $description "Takes a byte array and block size, and pushes a compressed byte array from bzip3." } ; HELP: decompress { $values byte-array: byte-array byte-array': byte-array } -{ $description Takes a valid bzip3 compressed { $link "byte-array" } , and pushes its decompressed form. } ; +{ $description Takes a valid bzip3 compressed byte array, and pushes its decompressed form. } ; HELP: internal-error { $values msg: object } @@ -19,7 +19,7 @@ HELP: internal-error HELP: invalid-block-size { $values size: object } { $description Throws an { $link invalid-block-size } error. } -{ $error-description Occurs if the given block size for compression is not in the range of 65 KiB and 511 MiB. } ; +{ $error-description Occurs if the given "block" size for compression is not in the range of 65 KiB and 511 MiB. } ; HELP: version { $values c-string: string } @@ -31,7 +31,7 @@ The { $vocab-link "compression.bzip3" } vocabulary can compress and decompress b bzip3 is best used with text or code, and hence the { $vocab-link "io.encodings" } vocabularies, specifically the { $link "io.encodings.string" } , { $vocab-link "io.encodings.utf8" } and { $vocab-link "io.encodings.ascii" } will be of help. -$nl + If you are an experienced user and would like to use the low level API of bzip3, the { $link "compression.bzip3.ffi" } library exposes the C bindings that allows for better performance via threading and other customizations. In order to use the functions imported you will need to use the { $vocab-link "alien" } vocabulary. ; diff --git a/extra/compression/bzip3/ffi/ffi-docs.factor b/extra/compression/bzip3/ffi/ffi-docs.factor index 9a2c8ceeff..abddaf3534 100644 --- a/extra/compression/bzip3/ffi/ffi-docs.factor +++ b/extra/compression/bzip3/ffi/ffi-docs.factor @@ -1,6 +1,6 @@ ! Copyright (C) 2022 Your name. ! See http://factorcode.org/license.txt for BSD license. -USING: classes.struct help.markup help.syntax kernel math ; +USING: classes.struct help.markup help.syntax kernel math compression.bzip3 ; IN: compression.bzip3.ffi HELP: bz3_bound @@ -8,113 +8,93 @@ HELP: bz3_bound { "input_size" object } { "size_t" object } } -{ $description "" } ; +{ $description Given an input size, outputs a possible output size after compression. Used in compression only. } ; HELP: bz3_compress { $values { "block_size" object } { "in" object } { "out" object } { "in_size" object } { "out_size" object } { "int" object } } -{ $description Available in the high level API. Usage of { $link "compression.bzip3.compress" } is encouraged. } ; +{ $description Available in the high level API. Usage of { $snippet "compress" } from the parent vocabulary is encouraged instead. } ; HELP: bz3_decode_block { $values { "state" object } { "buffer" object } { "size" object } { "orig_size" object } { "int32_t" object } } -{ $description "" } ; +{ $description Consult { $link "compression.bzip3.ffi" } for more details. } ; HELP: bz3_decode_blocks { $values { "states[]" object } { "buffers[]" object } { "sizes[]" object } { "orig_sizes[]" object } { "n" integer } } -{ $description "" } ; +{ $description Consult { $link "compression.bzip3.ffi" } for more details. } ; HELP: bz3_decompress { $values { "in" object } { "out" object } { "in_size" object } { "out_size" object } { "int" object } } -{ $description Available in the high level API. Usage of { $link "compression.bzip3.decompress" } is encouraged. } ; +{ $description Available in the high level API. Usage of { $snippet "decompress" } from the parent vocabulary is encouraged instead. } ; HELP: bz3_encode_block { $values { "state" struct } { "buffer" object } { "size" object } { "int32_t" object } } -{ $description "" } ; +{ $description Consult { $link "compression.bzip3.ffi" } for more details. } ; HELP: bz3_encode_blocks { $values { "states[]" object } { "buffers[]" object } { "sizes[]" object } { "n" integer } } -{ $description "" } ; +{ $description Consult { $link "compression.bzip3.ffi" } for more details. } ; HELP: bz3_free { $values { "state" object } } -{ $description "" } ; +{ $description Consult { $link "compression.bzip3.ffi" } for more details. } ; HELP: bz3_last_error { $values { "state" object } { "int8_t" object } } -{ $description "" } ; +{ $description Consult { $link "compression.bzip3.ffi" } for more details. } ; HELP: bz3_new { $values { "block_size" object } { "bz3_state*" object } } -{ $description "" } ; +{ $description Consult { $link "compression.bzip3.ffi" } for more details. } ; HELP: bz3_state -{ $class-description "" } ; +{ $class-description Structure for holding and passing state between low-level bzip3 functions. Consult { $link "compression.bzip3.ffi" } for more details. } ; HELP: bz3_strerror { $values { "state" object } { "c-string" object } } -{ $description "" } ; +{ $description Consult { $link "compression.bzip3.ffi" } for more details. } ; HELP: bz3_version { $values { "c-string" object } } -{ $description "" } ; +{ $description "Pushes the bzip3 version present on your system. compression.bz3's " { $snippet "version" } "is an alias for this word." } ; -HELP: s16 -{ $var-description "" } ; -HELP: s32 -{ $var-description "" } ; - -HELP: s8 -{ $var-description "" } ; - -HELP: state -{ $class-description "" } ; - -HELP: u16 -{ $var-description "" } ; - -HELP: u32 -{ $var-description "" } ; - -HELP: u64 -{ $var-description "" } ; - -HELP: u8 -{ $var-description "" } ; - -ARTICLE: "compression.bzip3.ffi" "compression.bzip3.ffi" -This vocabulary contains mainly high-level documentation. +ARTICLE: "compression.bzip3.ffi" "Compression.bzip3.ffi" +This vocabulary contains mainly high-level documentation. The words present in this vocabulary link to C functions and hence +must be used carefully. Some functions mutate their arguments. Consult your local installation of { $snippet "libbz3.h" } , or read it at -{ $url "https://github.com/kspalaiologos/bzip3/blob/master/include/libbz3.h" } for details that are up-to-date. +{ $url "https://github.com/kspalaiologos/bzip3/blob/master/include/libbz3.h" "GitHub" } for details that are up-to-date. + +For an idea of how to use bzip3's compression functions, see the { $url "https://github.com/kspalaiologos/bzip3/blob/master/examples" "bzip3 examples" } . ; ABOUT: "compression.bzip3.ffi" -- 2.34.1