bzip3: add full docs, fix lint problems

diff --git a/extra/compression/bzip3/bzip3-docs.factor b/extra/compression/bzip3/bzip3-docs.factor
index 0cc84b5656eb4f2d81ba3eaa6c1ec9b01c44c4e3..9ed73ea6f1e62a27454220db5ded12c2b9f60c88 100644 (file)
--- 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.
 ! 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
 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 }
 
 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 }
 
 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. }
 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 }
 
 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.
 
 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. ;
 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 9a2c8ceeffcc61e54489c222ddda911f76ae3570..abddaf3534dfe41062434036aeaa66db6e1d224b 100644 (file)
--- 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.
 ! 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
 IN: compression.bzip3.ffi
 
 HELP: bz3_bound


@@ -8,113 +8,93 @@ HELP: bz3_bound
     { "input_size" object }
     { "size_t" object }
 }
     { "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 }
 }
 
 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 }
 }
 
 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 }
 }
 
 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 }
 }
 
 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 }
 }
 
 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 }
 }
 
 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 }
 }
 
 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 }
 }
 
 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 }
 }
 
 HELP: bz3_new
 { $values
     { "block_size" object }
     { "bz3_state*" object }
 }

-{ $description "" } ;
+{ $description Consult { $link "compression.bzip3.ffi" } for more details. } ;

 
 HELP: bz3_state
 
 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 }
 }
 
 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 }
 }
 
 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
 
 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"
 ;
 
 ABOUT: "compression.bzip3.ffi"