First round of rewording and changes to documentation. Added ability to generate bloom man pages

zackcam · zackcam · commit cd8082610e4c · 2025-02-21T08:11:47.000Z
Signed-off-by: zackcam &lt;zackcam@amazon.com&gt;
diff --git a/Makefile b/Makefile
@@ -8,7 +8,7 @@ DATE ?= 2025-01-08
 
 # Path to the code repo.
 VALKEY_ROOT ?= ../valkey
-
+VALKEY_BLOOM_ROOT ?= ../valkey-bloom
 # Where to install man pages
 INSTALL_MAN_DIR ?= /usr/local/share/man
 
@@ -30,6 +30,10 @@ ifeq ("$(wildcard $(VALKEY_ROOT))","")
     $(error Please provide the VALKEY_ROOT variable pointing to the Valkey source code)
 endif
 
+ifeq ("$(wildcard $(VALKEY_BLOOM_ROOT))","")
+    $(error Please provide the VALKEY_ROOT variable pointing to the Valkey source code)
+endif
+
 ifeq ("$(shell which pandoc)","")
     $(error Please install pandoc)
 endif
@@ -54,7 +58,9 @@ endif
 
 documented_commands = $(wildcard commands/*.md)
 commands_json_files = $(wildcard $(VALKEY_ROOT)/src/commands/*.json)
-existing_commands = $(commands_json_files:$(VALKEY_ROOT)/src/commands/%.json=commands/%.md)
+bloom_commands_json_files = $(wildcard $(VALKEY_BLOOM_ROOT)/src/commands/*.json)
+existing_commands = $(commands_json_files:$(VALKEY_ROOT)/src/commands/%.json=commands/%.md) \
+                   $(bloom_commands_json_files:$(VALKEY_BLOOM_ROOT)/src/commands/%.json=commands/%.md)
 
 topics   = $(wildcard topics/*)
 commands = $(filter $(existing_commands),$(documented_commands))
@@ -65,7 +71,9 @@ topics_pics = $(filter-out %.md,$(topics))
 # ---- Temp files ----
 
 # JSON files for the commands that have a .md file (excluding undocumented commands).
-json_for_documented_commands = $(commands:commands/%.md=$(VALKEY_ROOT)/src/commands/%.json)
+json_for_documented_commands = \
+    $(patsubst commands/%.md,$(VALKEY_ROOT)/src/commands/%.json,$(filter $(commands_json_files:$(VALKEY_ROOT)/src/commands/%.json=commands/%.md),$(commands))) \
+    $(patsubst commands/%.md,$(VALKEY_BLOOM_ROOT)/src/commands/%.json,$(filter $(bloom_commands_json_files:$(VALKEY_BLOOM_ROOT)/src/commands/%.json=commands/%.md),$(commands)))
 
 $(BUILD_DIR)/.commands-per-group.json: $(VALKEY_ROOT)/src/commands/. utils/build-command-groups.py | $(BUILD_DIR)
 	utils/build-command-groups.py $(json_for_documented_commands) > $@~~
@@ -175,11 +183,14 @@ $(MAN_DIR)/man1/valkey-%.1.gz: topics/%.md $(man_scripts)
 	utils/preprocess-markdown.py --man --page-type program \
 	 --version $(VERSION) --date $(DATE) \$< \
 	 | utils/links-to-man.py - | $(to_man) > $@
-$(MAN_DIR)/man3/%.3valkey.gz: commands/%.md $(VALKEY_ROOT)/src/commands/%.json $(BUILD_DIR)/.commands-per-group.json $(man_scripts)
+$(MAN_DIR)/man3/%.3valkey.gz: commands/%.md $(BUILD_DIR)/.commands-per-group.json $(man_scripts)
+	$(eval VALKEY_ROOTS := $(VALKEY_ROOT) $(VALKEY_BLOOM_ROOT))
+	$(eval FINAL_ROOT := $(firstword $(foreach root,$(VALKEY_ROOTS),$(if $(wildcard $(root)/src/commands/$*.json),$(root)))))
+	$(if $(FINAL_ROOT),,$(eval FINAL_ROOT := $(lastword $(VALKEY_ROOTS))))
 	utils/preprocess-markdown.py --man --page-type command \
 	 --version $(VERSION) --date $(DATE) \
 	 --commands-per-group-json $(BUILD_DIR)/.commands-per-group.json \
-	 --valkey-root $(VALKEY_ROOT) $< \
+	 --valkey-root $(FINAL_ROOT) $< \
 	 | utils/links-to-man.py - | $(to_man) > $@
 $(MAN_DIR)/man5/%.5.gz: topics/%.md $(man_scripts)
 	utils/preprocess-markdown.py --man --page-type config \
diff --git a/commands/bf.add.md b/commands/bf.add.md
@@ -1,9 +1,9 @@
-Adds an item to a bloom filter, if the specified filter does not exist creates a default bloom filter with that name.
-## Arguments
-* key (required) - A Valkey key of Bloom data type
-* item (required) - Item to add
+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.
+
+If you want to create a bloom filter with non-standard options, use the `BF.INSERT` or `BF.RESERVE` command.
 
 ## Examples
+
 ```
 127.0.0.1:6379> BF.ADD key val
 1 
diff --git a/commands/bf.card.md b/commands/bf.card.md
@@ -1,8 +1,7 @@
 Gets the cardinality of a Bloom filter - number of items that have been successfully added to a Bloom filter. 
-## Arguments
-* key (required) - A Valkey key of Bloom data type
 
 ## Examples
+
 ```
 127.0.0.1:6379> BF.ADD key val
 1
diff --git a/commands/bf.exists.md b/commands/bf.exists.md
@@ -1,11 +1,14 @@
-Determines if a specified item has been added to the specified bloom filter.
-Syntax
+Determines if an item has been added to the bloom filter. 
+
+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
 
-## Arguments
-* key (required) -  A Valkey key of Bloom data type
-* item (required) -  The item that we are checking if it exists in the bloom object
 
 ## Examples
+
 ```
 127.0.0.1:6379> BF.ADD key val
 1
diff --git a/commands/bf.info.md b/commands/bf.info.md
@@ -1,17 +1,19 @@
-Returns information about a bloomfilter
+Returns information about a 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
+* 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
+* MAXSCALEDCAPACITY - Returns the maximum capacity that can be reached before an error occurs
 
-## Arguments
-* key (required) - A valkey key of bloom data type
-* CAPACITY (optional) - Returns the number of unique items that would need to be added before scaling would happen
-* SIZE (optional) - Returns the memory size which is the number of bytes allocated
-* FILTERS (optional) - Returns the number of filters in the specified key
-* ITEMS (optional) - Returns the number of unique items that have been added the the Bloom filter
-* ERROR (optional) - Returns the false positive rate for the bloom filter
-* EXPANSION (optional) - Returns the expansion rate
-* MAXSCALEDCAPACITY (optional) - 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
  
 ## Examples
+
 ```
 127.0.0.1:6379> BF.ADD key val
 1
diff --git a/commands/bf.insert.md b/commands/bf.insert.md
@@ -1,19 +1,21 @@
-Creates a bloom object 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 after
+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
+
+## 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
+* 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
 
-## Arguments
 Due to the nature of  NONSCALING and VALIDATESCALETO arguments, specifying NONSCALING and VALIDATESCALETO isn't allowed
-* key (required) - Is the key name for a Bloom filter to add the item to
-* CAPACITY capacity (optional) -  capacity for the inital bloom filter
-* ERROR fp_error (optional)- The false positive rate for the bloom filter
-* EXPANSION expansion(optional) - The expansion rate for a scaling filter
-* NOCREATE (optional) - Will not create the bloom filter and add items if the filter does not exist already
-* TIGHTENING (optional) - The tightening ratio for the bloom filter
-* SEED (optional) - The seed the hash functions will use
-* NONSCALING (optional) - Will make it so the filter can not scale
-* VALIDATESCALETO validatescaleto (optional) - Checks if the filter could scale to this capacity and if not show an error and don’t create the bloom filter
-* ITEMS (optional) - Items we will add to the bloom filter
 
 ## Examples
+
 ```
 127.0.0.1:6379> BF.INSERT key ITEMS item1 item2
 1) (integer) 1
@@ -28,13 +30,13 @@ Due to the nature of  NONSCALING and VALIDATESCALETO arguments, specifying NONSC
 
 ```
 127.0.0.1:6379> BF.INSERT key NONSCALING VALIDATESCALETO 100
-cannot use NONSCALING and VALIDATESCALETO options together
-127.0.0.1:6379> BF.INSERT key CAPACITY 1000  VALIDATESCALETO 999999999999999999999 ITEMS item2 item3
-provided VALIDATESCALETO causes bloom object to exceed memory limit
-127.0.0.1:6379> BF.INSERT key VALIDATESCALETO 999999999999999999999 EXPANSION 1 ITEMS item2 item3
-provided VALIDATESCALETO causes false positive to degrade to 0
+(error) ERR cannot use NONSCALING and VALIDATESCALETO options together
+127.0.0.1:6379> BF.INSERT key CAPACITY 1000  VALIDATESCALETO 999999999999999999 ITEMS item2 item3
+(error) ERR provided VALIDATESCALETO causes bloom object to exceed memory limit
+127.0.0.1:6379> BF.INSERT key VALIDATESCALETO 999999999999999999 EXPANSION 1 ITEMS item2 item3
+(error) ERR provided VALIDATESCALETO causes false positive to degrade to 0
 ```
 ```
 127.0.0.1:6379> BF.INSERT key NOCREATE ITEMS item1 item2
-not found
+(error) ERR not found
 ```
diff --git a/commands/bf.load.md b/commands/bf.load.md
@@ -1,4 +1 @@
 Loads a bloom filter from a dump of an existing bloom object with all the properties and bit vector dump.
-## Arguments
-* key (required) - Is the key name for a Bloom filter to add the item to
-* dump (required) - Is the dump we are restoring
diff --git a/commands/bf.madd.md b/commands/bf.madd.md
@@ -1,8 +1,9 @@
-Adds one or more items to a Bloom Filter, if the specified filter does not exist creates a default bloom filter with that name.
-## Arguments
-* key (required) - Is the key name for a Bloom filter to add the item to
-* item (requires at least 1 item but can add as many as wanted ) - Is the item/s to add
+Adds one or more items to a Bloom Filter, if the bloom filter does not exist creates a default bloom filter.
+
+If you want to create a bloom filter with non-standard options, use the `BF.INSERT` or `BF.RESERVE` command.
+
 ## Examples
+
 ```
 127.0.0.1:6379> BF.MADD key item1 item2
 1) (integer) 1
diff --git a/commands/bf.mexists.md b/commands/bf.mexists.md
@@ -1,8 +1,13 @@
-Determines if one or more items has been added to the specified bloom filter
-## Arguments
-* key (required) - A Valkey key of Bloom data type
-* item (requires at least 1 item but can add as many as desired) -  The item/s that we are checking if it exists in the bloom object
+Determines if one or more items has been added to a bloom filter. 
+
+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
+
 ## Examples
+
 ```
 127.0.0.1:6379> BF.MADD key item1 item2
 1) (integer) 1
diff --git a/commands/bf.reserve.md b/commands/bf.reserve.md
@@ -1,12 +1,14 @@
 Creates an empty bloom object with the capacity and false positive rate specified
-## Arguments
-* key (required) -  A Valkey key of Bloom data type
-* error_rate (required) - The fp rate the bloom filter will be created with
-* capacity (required) -  The starting capacity the bloom filter will be created with
-* EXPANSION expansion(optional)- The rate in which filters will increase by
-* NONSCALING (optional) - Setting this will make it so the bloom object can’t expand past its initial capacity
+
+## 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
 
 ## Examples
+
 ```
 127.0.0.1:6379> BF.RESERVE key 0.01 1000
 OK
diff --git a/groups.json b/groups.json
@@ -4,7 +4,7 @@
     "description": "Operations on the Bitmap data type"
   },
   "bloom": {
-    "display": "Bloom",
+    "display": "Bloom filter",
     "description": "Operations on the Bloom filter data type"
   },
   "cluster": {
diff --git a/resp2_replies.json b/resp2_replies.json
@@ -64,8 +64,8 @@
   ],
   "BF.ADD": [
     "One of the following:",
-    "* [Integer reply](../topics/protocol.md#integers): '1'. The item was successfully added",
-    "* [Integer reply](../topics/protocol.md#integers): '0'. The item already existed in the bloom filter",
+    "* [Integer reply](../topics/protocol.md#integers): `1` if the item was successfully added",
+    "* [Integer reply](../topics/protocol.md#integers): `0` if the item already existed in the bloom filter",
     "",
     "The command may fail with an error for several reasons: if the wrong number of arguments are provided, if attempting to add to a non scaling filter that is full"
   ],
@@ -76,23 +76,23 @@
   ],
   "BF.EXISTS": [
     "One of the following:",
-    "* [Integer reply](../topics/protocol.md#integers): '1'. The item exists in the bloom filter",
-    "* [Integer reply](../topics/protocol.md#integers): '0'. The bloom filter does not exist or the item has not been added to the bloom filter",
+    "* [Integer reply](../topics/protocol.md#integers): `1` if the item exists in the bloom filter",
+    "* [Integer reply](../topics/protocol.md#integers): `0` if the bloom filter does not exist or the item has not been added to the bloom filter",
     "",
     "The command will fail if the wrong number of arguments are provided"
   ],
   "BF.INFO": [
     "When no optional arguments are provided:",
-    "[Array reply](../topics/protocol.md#arrays): List of information about the bloom filter.",
-    "When an optional argument is provided:",
+    "* [Array reply](../topics/protocol.md#arrays): List of information about the bloom filter.",
+    "When an optional argument excluding ERROR is provided:",
     "* [Integer reply](../topics/protocol.md#integers): argument value",
-    "* [String reply??](../topics/protocol.md#simple-strings): argument value",
+    "When ERROR is provided as an optional argument:",
+    "* [String reply](../topics/protocol.md#simple-strings): argument value",
     "",
     "The command may fail with an error for several reasons: if the wrong number of arguments are provided, if trying to get MAXSCALEDCAPACITY of a non scaling filter"
   ],
   "BF.INSERT": [
     "[Array reply](../topics/protocol.md#arrays): Array of ints (1’s and 0’s) - if filter already exists or if creation was successful. An empty array if no items are provided",
-    "[String reply??](../topics/protocol.md#simple-strings): not found, if the filter does not exist and NOCREATE is specified",
     "",
     "The command may fail with an error for several reasons: if the wrong number of arguments are provided, if the provided VALIDATESCALETO is not possible, if the provided optional args are not valid"
   ],
diff --git a/resp3_replies.json b/resp3_replies.json
@@ -64,8 +64,8 @@
   ],
   "BF.ADD": [
     "One of the following:",
-    "* [Integer reply](../topics/protocol.md#integers): '1'. The item was successfully added",
-    "* [Integer reply](../topics/protocol.md#integers): '0'. The item already existed in the bloom filter",
+    "* [Integer reply](../topics/protocol.md#integers): `1` if the item was successfully added",
+    "* [Integer reply](../topics/protocol.md#integers): `0` if the item already existed in the bloom filter",
     "",
     "The command may fail with an error for several reasons: if the wrong number of arguments are provided, if attempting to add to a non scaling filter that is full"
   ],
@@ -76,23 +76,23 @@
   ],
   "BF.EXISTS": [
     "One of the following:",
-    "* [Integer reply](../topics/protocol.md#integers): '1'. The item exists in the bloom filter",
-    "* [Integer reply](../topics/protocol.md#integers): '0'. The bloom filter does not exist or the item has not been added to the bloom filter",
+    "* [Integer reply](../topics/protocol.md#integers): `1` if the item exists in the bloom filter",
+    "* [Integer reply](../topics/protocol.md#integers): `0` if the bloom filter does not exist or the item has not been added to the bloom filter",
     "",
     "The command will fail if the wrong number of arguments are provided"
   ],
   "BF.INFO": [
     "When no optional arguments are provided:",
-    "[Array reply](../topics/protocol.md#arrays): List of information about the bloom filter.",
-    "When an optional argument is provided:",
+    "* [Array reply](../topics/protocol.md#arrays): List of information about the bloom filter.",
+    "When an optional argument excluding ERROR is provided:",
     "* [Integer reply](../topics/protocol.md#integers): argument value",
-    "* [String reply??](../topics/protocol.md#simple-strings): argument value",
+    "When ERROR is provided as an optional argument:",
+    "* [String reply](../topics/protocol.md#simple-strings): argument value",
     "",
     "The command may fail with an error for several reasons: if the wrong number of arguments are provided, if trying to get MAXSCALEDCAPACITY of a non scaling filter"
   ],
   "BF.INSERT": [
     "[Array reply](../topics/protocol.md#arrays): Array of ints (1’s and 0’s) - if filter already exists or if creation was successful. An empty array if no items are provided",
-    "[String reply??](../topics/protocol.md#simple-strings): not found, if the filter does not exist and NOCREATE is specified",
     "",
     "The command may fail with an error for several reasons: if the wrong number of arguments are provided, if the provided VALIDATESCALETO is not possible, if the provided optional args are not valid"
   ],
diff --git a/topics/bloomfilters.md b/topics/bloomfilters.md
diff --git a/topics/data-types.md b/topics/data-types.md

Original file line number	Diff line number	Diff line change
`@@ -1,8 +1,7 @@`
`1`	`1`	`Gets the cardinality of a Bloom filter - number of items that have been successfully added to a Bloom filter.`
`2`		`-## Arguments`
`3`		`-* key (required) - A Valkey key of Bloom data type`
`4`	`2`
`5`	`3`	`## Examples`
	`4`	`+`
`6`	`5`	```
`7`	`6`	`127.0.0.1:6379> BF.ADD key val`
`8`	`7`	`1`