Audit and make documentation for command JSON.CLEAR consistent (DiceD…

…B#887) Co-authored-by: Neville Mehta <[email protected]>
lucifercr07 · Oct 4, 2024 · 1953a10 · 1953a10
1 parent 1635582
commit 1953a10
Showing 1 changed file with 56 additions and 79 deletions.
diff --git a/docs/src/content/docs/commands/JSON.CLEAR.md b/docs/src/content/docs/commands/JSON.CLEAR.md
@@ -3,116 +3,93 @@ title: JSON.CLEAR
 description: Documentation for the DiceDB command JSON.CLEAR
 ---
 
-The `JSON.CLEAR` command is part of the DiceDBJSON module, which allows you to manipulate JSON data stored in DiceDB. This command is used to clear the value at a specified path in a JSON document, effectively setting it to an empty state. This can be particularly useful when you want to reset a part of your JSON document without removing the key itself.
+The `JSON.CLEAR` command allows you to manipulate JSON data stored in DiceDB. This command is used to clear the value at a specified path in a JSON document, effectively setting it to an empty state. This can be particularly useful when you want to reset a part of your JSON document without removing the key itself.
+
+## Syntax
+
+```
+JSON.CLEAR key [path]
+```
 
 ## Parameters
 
-- `key`: (String) The key under which the JSON document is stored.
-- `path`: (String) The path within the JSON document that you want to clear. The path should be specified in JSONPath format. If the path is omitted, the root path (`$`) is assumed.
+| Parameter | Description                                                               | Type    | Required |
+|-----------|---------------------------------------------------------------------------|---------|----------|
+| `key`     | (String) The key under which the JSON document is stored.                 | String  | Yes      |
+| `path`    | (String) The path within the JSON document that you want to clear. The path should be specified in JSONPath format. If the path is omitted, the root path (`$`) is assumed. | String  | No       |
 
-## Return Value
+## Return values
 
-- `Integer`: The number of paths that were cleared.
+| Condition                                      | Return Value                                      |
+|------------------------------------------------|---------------------------------------------------|
+| Command is successful                          | `Integer` (The number of paths that were cleared) |
+| Syntax or specified constraints are invalid    | error                                             |
 
 ## Behaviour
 
 When the `JSON.CLEAR` command is executed, it traverses the JSON document stored at the specified key and clears the value at the given path. The clearing operation depends on the type of the value at the path:
 
 - For objects, it removes all key-value pairs.
 - For arrays, it removes all elements.
-- For strings, it sets the value to an empty string.
+- For strings, the value remaines unchanged.
 - For numbers, it sets the value to `0`.
-- For booleans, it sets the value to `false`.
+- For booleans, the value remaines unchanged.
 
 If the specified path does not exist, the command does nothing and returns `0`.
 
-## Error Handling
+## Errors
 
 The `JSON.CLEAR` command can raise the following errors:
 
 - `(error) ERR wrong number of arguments for 'json.clear' command`: This error is raised if the command is called with an incorrect number of arguments.
-- `(error) ERR key does not exist`: This error is raised if the specified key does not exist in the DiceDB database.
-- `(error) ERR path is not a valid JSONPath`: This error is raised if the specified path is not a valid JSONPath expression.
-- `(error) ERR path does not exist`: This error is raised if the specified path does not exist within the JSON document.
-
-## Example Usage
+- `(error) ERR could not perform this operation on a key that doesn't exist`: This error is raised if the specified key does not exist in the DiceDB database.
+- `(error) ERR invalid JSONPath`: This error is raised if the specified path is not a valid JSONPath expression.
+- `(error) ERR Existing key has wrong Dice type`: This error is raised if the key exists but the value is not of the expected JSON type and encoding.
 
-### Example 1: Clearing a JSON Object
-
-Suppose you have a JSON document stored under the key `user:1001`:
-
-```json
-{
-  "name": "John Doe",
-  "age": 30,
-  "address": {
-    "street": "123 Main St",
-    "city": "Anytown"
-  }
-}
-```
-
-To clear the `address` object, you would use the following command:
-
-```sh
-JSON.CLEAR user:1001 $.address
-```
+Note: If the specified path does not exist within the JSON document, the command will not raise an error but will simply not modify anything.
 
-After executing this command, the JSON document would be:
-
-```json
-{
-  "name": "John Doe",
-  "age": 30,
-  "address": {}
-}
-```
-
-### Example 2: Clearing an Array
-
-Suppose you have a JSON document stored under the key `user:1002`:
-
-```json
-{
-  "name": "Jane Doe",
-  "hobbies": ["reading", "swimming", "hiking"]
-}
-```
-
-To clear the `hobbies` array, you would use the following command:
-
-```sh
-JSON.CLEAR user:1002 $.hobbies
-```
+## Example Usage
 
-After executing this command, the JSON document would be:
+### Clearing a JSON Object
 
-```json
-{
-  "name": "Jane Doe",
-  "hobbies": []
-}
+```bash
+127.0.0.1:7379> JSON.SET user:1001 $ '{"name": "John Doe", "age": 30, "address": {"street": "123 Main St", "city": "Anytown"}}'
+OK
+127.0.0.1:7379> JSON.CLEAR user:1001 $.address
+(integer) 1
+127.0.0.1:7379> JSON.GET user:1001
+"{\"name\":\"John Doe\",\"age\":30,\"address\":{}}"
 ```
 
-### Example 3: Clearing the Root Path
-
-Suppose you have a JSON document stored under the key `user:1003`:
+### Clearing a Number
 
-```json
-{
-  "name": "Alice",
-  "age": 25
-}
+```bash
+127.0.0.1:7379> JSON.SET user:1001 $ '{"name": "John Doe", "age": 30, "address": {"street": "123 Main St", "city": "Anytown"}}'
+OK
+127.0.0.1:7379> JSON.CLEAR user:1001 $.age
+(integer) 1
+127.0.0.1:7379> JSON.GET user:1001
+"{\"name\":\"John Doe\",\"age\":0,\"address\":{\"street\":\"123 Main St\",\"city\":\"Anytown\"}}"
 ```
 
-To clear the entire JSON document, you would use the following command:
+### Clearing an Array
 
-```sh
-JSON.CLEAR user:1003
+```bash
+127.0.0.1:7379> JSON.SET user:1002 $ '{"name": "Jane Doe", "hobbies": ["reading", "swimming", "hiking"]}'
+OK
+127.0.0.1:7379> JSON.CLEAR user:1002 $.hobbies
+(integer) 1
+127.0.0.1:7379> JSON.GET user:1002
+"{\"name\":\"Jane Doe\",\"hobbies\":[]}"
 ```
 
-After executing this command, the JSON document would be:
+### Clearing the Root Path
 
-```json
-{}
+```bash
+127.0.0.1:7379> JSON.SET user:1003 $ '{"name": "Alice", "age": 25}'
+OK
+127.0.0.1:7379> JSON.CLEAR user:1003
+(integer) 1
+127.0.0.1:7379> JSON.GET user:1003
+"{}"
 ```