From 5dacfd0dfed14865b2a1f27c8832d598e3befd07 Mon Sep 17 00:00:00 2001
From: Bennett Wetters <contact@bendo.org>
Date: Sat, 3 Aug 2024 21:02:44 +0200
Subject: [PATCH] docs: Update README and code comments

---
 README.md | 51 ++++++++++++++++++++++++++++++---------------------
 main.go   |  6 ++++--
 2 files changed, 34 insertions(+), 23 deletions(-)

diff --git a/README.md b/README.md
index 8eaeb3f..577f3ee 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,7 @@
 `spaceapid` serves a [SpaceAPI](https://spaceapi.io)-compatible JSON on port 8080:
 
 ```shell
-$ curl http://[::1]:8080 | jq
+$ curl http://localhost:8080 | jq
 {
   "api_compatibility": [
     "14"
@@ -28,26 +28,6 @@ The config consists of three parts:
 
 See [Running](#Running) for details.
 
-## Updating values
-
-The state of the boolean `state->open` property can be modified via `/state/open`:
-
-```shell
-curl -X PUT -u user:password -d true http://[::1]:8080/state/open
-```
-
-The same is true for the endpoints for sensors configured under `"dynamic"`.
-Currently only the sensors with the `value/unit/location/name/description` schema are implemented.
-At the time of writing this includes `temperature`, `barometer`, `humidity`, `beverage_supply`, `power_consumption`, and `account_balance`.
-Out-of-spec sensors may be used as well, as long as they share the same schema.
-
-```shell
-curl -X PUT -u user:password -d 23.42 http://[::1]:8080/sensors/{temperature,humidity,...}[/location[/name]]
-```
-
-As can be seen in the example, the http urls are generated from sensor type and optionally `location` and `name`.
-Depending on sensor type, `location` might be required for your sensors, see the schema for details.
-
 ## Building
 
 See the `go.mod` file for minimum required Go version.
@@ -62,3 +42,32 @@ env CONFIG_PATH=config-template.json go run .
 # OR
 go run . -c config-credentials.json,config-dynamic.json,config-response.json
 ```
+
+## Updating values
+
+The state of the boolean `state->open` and `state->message` property can be modified via `/state/{open,message}`:
+
+```shell
+curl -X PUT -u user:password -d true http://localhost:8080/state/open
+curl -X PUT -u user:password -d "Nur mit Passierschein A38 :3" http://localhost:8080/state/message
+```
+
+As `state->message` is optional, its value can be deleted by using the `PUT` method with an empty payload, or by using `DELETE`:
+
+```shell
+curl -X PUT -u user:password -d "" http://localhost:8080/state/message
+# OR
+curl -X DELETE -u user:password http://localhost:8080/state/message
+```
+
+The same updating procedure applies for the endpoints for sensors configured under `"dynamic"`.
+Currently only the sensors with the `value/unit/location/name/description` schema are implemented.
+At the time of writing this includes `temperature`, `barometer`, `humidity`, `beverage_supply`, `power_consumption`, and `account_balance`.
+Out-of-spec sensors may be used as well, as long as they share the same schema.
+
+```shell
+curl -X PUT -u user:password -d 23.42 http://localhost:8080/sensors/{temperature,humidity,...}[/location[/name]]
+```
+
+As can be seen in the example, the http urls are generated from sensor type and optionally `location` and `name`.
+Depending on sensor type, `location` might be required for your sensors, see the schema for details.
diff --git a/main.go b/main.go
index 2581e17..35b564d 100644
--- a/main.go
+++ b/main.go
@@ -50,20 +50,22 @@ func main() {
 		os.Exit(0)
 	}(&conf.Response)
 
-	// Register HTTP handlers
+	// Root handler
 	http.HandleFunc("GET /{$}",
 		handlers.Root(&conf.Response),
 	)
+	// state->open
 	http.HandleFunc("PUT /state/open",
 		handlers.StateOpen(conf.Credentials, conf.Dynamic.State.Open.AllowedCredentials, &conf.Response.State),
 	)
+	// state->message
 	http.HandleFunc("PUT /state/message",
 		handlers.StateMessagePUT(conf.Credentials, conf.Dynamic.State.Open.AllowedCredentials, &conf.Response.State),
 	)
 	http.HandleFunc("DELETE /state/message",
 		handlers.StateMessageDELETE(conf.Credentials, conf.Dynamic.State.Open.AllowedCredentials, &conf.Response.State),
 	)
-	// Register handler for environmental sensors
+	// Register handlers for environmental sensors
 	for sensorType, envSensorConfigs := range conf.Dynamic.Sensors {
 		for i, envSensorConfig := range envSensorConfigs {
 			urlPattern := "PUT " + util.GetSensorURLPath(