Changes based on feedback for bloom commands and documentation

Signed-off-by: zackcam <[email protected]>

Author: zackcam

README.md

@@ -7,11 +7,11 @@ for generating content for the website and man pages.
 
 This repo comes with a Makefile to build and install man pages.
 
-    make VALKEY_ROOT=path/to/valkey
+    make VALKEY_ROOT=path/to/valkey VALKEY_BLOOM_ROOT=path/to/valkey-bloom
     sudo make install INSTALL_MAN_DIR=/usr/local/share/man
 
 Prerequisites: GNU Make, Python 3, Python 3 YAML (pyyaml), Pandoc.
-Additionally, the scripts need access to the valkey code repo,
+Additionally, the scripts need access to the valkey and valkey-bloom code repos,
 where metadata files about the commands are stored.
 
 The pages are generated under `_build/man/` by default. The default install

commands/bf.add.md

@@ -1,6 +1,8 @@
-Adds an item to a bloom filter, if the specified bloom filter does not exist creates a bloom filter with default configurations with that name.
+Adds a single item to a bloom filter. If the specified bloom filter does not exist, a bloom filter is created with the provided name with default properties.
 
-If you want to create a bloom filter with non-standard options, use the `BF.INSERT` or `BF.RESERVE` command.
+To add multiple items to a bloom filter, you can use the BF.MADD or BF.INSERT commands.
+
+If you want to create a bloom filter with non-default properties, use the `BF.INSERT` or `BF.RESERVE` command.
 
 ## Examples
 

commands/bf.card.md

@@ -1,4 +1,4 @@
-Gets the cardinality of a Bloom filter - number of items that have been successfully added to a Bloom filter. 
+Returns the cardinality of a Bloom filter which is the number of items that have been successfully added to it. 
 
 ## Examples
 
@@ -7,6 +7,6 @@ Gets the cardinality of a Bloom filter - number of items that have been successf
 1
 127.0.0.1:6379> BF.CARD key
 1
-127.0.0.1:6379> BF.CARD missing
+127.0.0.1:6379> BF.CARD nonexistentkey
 0
 ```

commands/bf.exists.md

@@ -1,11 +1,10 @@
-Determines if an item has been added to the bloom filter. 
+Determines if an item has been added to the bloom filter previously. 
 
 A Bloom filter has two possible responses when you check if an item exists:
 
-* "No" (Definite) - If the filter says an item is NOT present, this is 100% certain. The item is definitely not in the set.
-
-* "Maybe" (Probabilistic) - If the filter says an item IS present, this is uncertain. There's a chance it's a false positive. The item might be in the set, but may not be
+* 0 - The item definitely does not exist since with bloom filters, false negatives are not possible.
 
+* 1 - The item exists with a given false positive (fp) percentage. There is an fp rate % chance that the item does not exist. You can create bloom filters with a more strict false positive rate as needed.
 
 ## Examples
 
@@ -14,6 +13,6 @@ A Bloom filter has two possible responses when you check if an item exists:
 1
 127.0.0.1:6379> BF.EXISTS key val
 1
-127.0.0.1:6379> BF.EXISTS key missing
+127.0.0.1:6379> BF.EXISTS key nonexistent
 0
 ```

commands/bf.info.md

@@ -1,13 +1,13 @@
-Returns information about a bloom filter
+Returns usage information and properties of a specific bloom filter
 
 ## Info Fields
 
-* CAPACITY - Returns the number of unique items that would need to be added before scaling would happen
-* SIZE - Returns the number of bytes allocated
+* CAPACITY - The number of unique items that would need to be added before a scale out occurs or (non scaling) before it rejects addition of unique items. 
+* SIZE - The number of bytes allocated by this bloom filter.
 * FILTERS - Returns the number of filters in the specified key
-* ITEMS - Returns the number of unique items that have been added the the bloom filter
-* ERROR - Returns the false positive rate for the bloom filter
-* EXPANSION - Returns the expansion rate
+* ITEMS - The number of unique items that have been added to the bloom filter
+* ERROR - The false positive rate of the bloom filter
+* EXPANSION - The expansion rate of the bloom filter. Non scaling filters will have an expansion rate of nil.
 * MAXSCALEDCAPACITY - Returns the maximum capacity that can be reached before an error occurs
 
 If none of the optional fields are specified, all the fields will be returned. MAXSCALEDCAPACITY will be an unrecognized argument on non scaling filters

commands/bf.insert.md

@@ -1,16 +1,18 @@
-Creates a bloom filter with the specified parameters. If a parameter is not specified then the default value will be used. If ITEMS is specified then it will also attempt to add all items specified
+If the bloom filter does not exist under the specified name, a bloom filter is created with the specified parameters. Default properties will be used if the options below are not specified.
+
+When the ITEMS option is provided, all items provided will be attempted to be added.
 
 ## Insert Fields
 
-* CAPACITY capacity -  capacity for the initial bloom filter
-* ERROR `fp_error` - The false positive rate for the bloom filter
-* EXPANSION expansion - The expansion rate for a scaling filter
+* CAPACITY `capacity` -  The number of unique items that would need to be added before a scale out occurs or (non scaling) before it rejects addition of unique items. 
+* ERROR `fp_error` - The false positive rate of the bloom filter
+* EXPANSION `expansion` - This option will specify the bloom filter as scaling and controls the size of the sub filter that will be created upon scale out / expansion of the bloom filter.
 * NOCREATE  - Will not create the bloom filter and add items if the filter does not exist already
 * TIGHTENING `tightening_ratio` - The tightening ratio for the bloom filter
-* SEED seed - The seed the hash functions will use
-* NONSCALING - Will make it so the filter can not scale
-* VALIDATESCALETO `validatescaleto` - Checks if the filter could scale to this capacity and if not show an error and don’t create the bloom filter
-* ITEMS item - One or more items we will add to the bloom filter
+* SEED `seed` - The seed the hash functions will use
+* NONSCALING - This option will configure the bloom filter as non scaling; it cannot expand / scale beyond its specified capacity.
+* VALIDATESCALETO `validatescaleto` - Validates if the filter can scale out and reach to this capacity based on limits and if not, return an error without creating the bloom filter
+* ITEMS `item` - One or more items to be added to the bloom filter
 
 Due to the nature of  NONSCALING and VALIDATESCALETO arguments, specifying NONSCALING and VALIDATESCALETO isn't allowed
 
@@ -20,7 +22,7 @@ Due to the nature of  NONSCALING and VALIDATESCALETO arguments, specifying NONSC
 127.0.0.1:6379> BF.INSERT key ITEMS item1 item2
 1) (integer) 1
 2) (integer) 1
-# This does not update the capcity but uses the origianl filters values
+# This does not update the capacity since the filter already exists. It only adds the provided items.
 127.0.0.1:6379> BF.INSERT key CAPACITY 1000 ITEMS item2 item3
 1) (integer) 0
 2) (integer) 1

commands/bf.load.md

@@ -1 +1 @@
-Loads a bloom filter from a dump of an existing bloom object with all the properties and bit vector dump.
+Restores a bloom filter from a dump of an existing bloom filter with all of its specific the properties and bit vector dump of sub filter/s. This command is only generated during AOF Rewrite to restore a bloom filter in the future.

commands/bf.madd.md

@@ -1,6 +1,6 @@
-Adds one or more items to a Bloom Filter, if the bloom filter does not exist creates a default bloom filter.
+Adds one or more items to a bloom filter. If the specified bloom filter does not exist, a bloom filter is created with the provided name with default properties
 
-If you want to create a bloom filter with non-standard options, use the `BF.INSERT` or `BF.RESERVE` command.
+If you want to create a bloom filter with non-default properties, use the `BF.INSERT` or `BF.RESERVE` command.
 
 ## Examples
 

commands/bf.mexists.md

@@ -1,10 +1,10 @@
-Determines if one or more items has been added to a bloom filter. 
+Determines if the provided item/s have been added to a bloom filter previously.
 
 A Bloom filter has two possible responses when you check if an item exists:
 
-* "No" (Definite) - If the filter says an item is NOT present, this is 100% certain. The item is definitely not in the set.
+* 0 - The item definitely does not exist since with bloom filters, false negatives are not possible.
 
-* "Maybe" (Probabilistic) - If the filter says an item IS present, this is uncertain. There's a chance it's a false positive. The item might be in the set, but may not be
+* 1 - The item exists with a given false positive (fp) percentage. There is an fp rate % chance that the item does not exist. You can create bloom filters with a more strict false positive rate as needed.
 
 ## Examples
 

commands/bf.reserve.md

@@ -1,11 +1,13 @@
-Creates an empty bloom object with the capacity and false positive rate specified
+Creates an empty bloom filter with the capacity and false positive rate specified. By default, a scaling filter is created with the default expansion rate.
+
+To specify the scaling / non scaling nature of the bloom filter, use the options: NONSCALING or SCALING <expansion rate>. It is invalid to provide both options together.
 
 ## Reserve fields
 
-* error_rate - The false positive rate the bloom filter will be created with
-* capacity -  The starting capacity the bloom filter will be created with
-* EXPANSION expansion - The rate in which filters will increase by
-* NONSCALING - Setting this will make it so the bloom object can’t expand past its initial capacity
+* error_rate - The false positive rate of the bloom filter
+* capacity -  The number of unique items that would need to be added before a scale out occurs or (non scaling) before it rejects addition of unique items. 
+* EXPANSION expansion - This option will specify the bloom filter as scaling and controls the size of the sub filter that will be created upon scale out / expansion of the bloom filter.
+* NONSCALING - This option will configure the bloom filter as non scaling; it cannot expand / scale beyond its specified capacity.
 
 ## Examples