From 4622a4eaeecc5ed59fdc406dd2bd46c54639df08 Mon Sep 17 00:00:00 2001
From: John Blackbourn <johnbillion@gmail.com>
Date: Fri, 23 Aug 2024 14:09:28 +0100
Subject: [PATCH] Docs.

---
 readme.md                   |  2 +-
 tests/bin/build-wp-types.sh |  6 ++++++
 tests/bin/test.sh           | 11 ++++++++++-
 3 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/readme.md b/readme.md
index 4b71cc0..59a2bf0 100644
--- a/readme.md
+++ b/readme.md
@@ -253,7 +253,7 @@ Schemas are available via an OPTIONS request to the REST API endpoints, but the
 
 ### Are these schemas automatically generated from WordPress core?
 
-No. I started down that path (using [wp-parser-lib](https://github.com/johnbillion/wp-parser-lib)) but realised it's quicker to generate them manually and then copy most of the documentation from core, especially as I'm adding extra documentation and schemas for properties when I can.
+No, but they are automatically tested against output from WordPress core to ensure their correctness. Extra documentation and schemas for properties have been added where possible, so generating them directly from WordPress core isn't desirable.
 
 ### How do I know the schemas are accurate?
 
diff --git a/tests/bin/build-wp-types.sh b/tests/bin/build-wp-types.sh
index 68647d4..51b0a60 100755
--- a/tests/bin/build-wp-types.sh
+++ b/tests/bin/build-wp-types.sh
@@ -4,18 +4,24 @@
 # -o pipefail Produce a failure return code if any command errors
 set -eo pipefail
 
+# Set additionalProperties to false for all partial schemas
 for file in schemas/rest-api/partials/**/*.json
 do
 	./node_modules/node-jq/bin/jq --tab '. + { "additionalProperties": false }' "$file" > tmp && mv tmp "$file"
 done
 
+# Generate TypeScript types
 ./node_modules/.bin/json2ts -i schema.json -o packages/wp-types/index.ts --style.trailingComma=all --style.useTabs
 
+# Revert additionalProperties
 for file in schemas/rest-api/partials/**/*.json
 do
 	./node_modules/node-jq/bin/jq --tab 'del(.additionalProperties)' "$file" > tmp && mv tmp "$file"
 done
 
+# Append append.ts to the generated types
 cat packages/wp-types/append.ts >> packages/wp-types/index.ts
+
+# Don't export the partial interfaces
 sed -i.bak 's/export interface WP_REST_API_Partial_/interface WP_REST_API_Partial_/g' packages/wp-types/index.ts
 rm packages/wp-types/index.ts.bak
diff --git a/tests/bin/test.sh b/tests/bin/test.sh
index cc9a9cb..c4a535d 100755
--- a/tests/bin/test.sh
+++ b/tests/bin/test.sh
@@ -4,6 +4,7 @@
 # -o pipefail Produce a failure return code if any command errors
 set -eo pipefail
 
+# Validate a schema file
 function validate_schema() {
 	local file="$1"
 	local base=${file//schemas\//}
@@ -18,6 +19,7 @@ function validate_schema() {
 	./node_modules/.bin/ajv validate --spec=draft2019 --strict --strict-schema=false -c ajv-formats -m tests/external-schemas/hyper-schema.json -r schema.json -r $rflag -s "$file" -d "tests/data/$filename/*.json"
 }
 
+# Modify a schema file using a jq transformation and an optional jq condition
 function modify_schema() {
 	local file="$1"
 	local changes="$2"
@@ -35,6 +37,7 @@ function modify_schema() {
 	mv tmp "$file"
 }
 
+# Cleanup function to remove unevaluatedProperties and additionalProperties
 function cleanup() {
 	for file in schemas/rest-api/*.json
 	do
@@ -47,15 +50,20 @@ function cleanup() {
 	done
 }
 
+# Files to ignore when disallowing additional properties
 IGNORE_FILES=("schemas/rest-api/error.json")
 
+# Always cleanup regardless of how the script exits
 trap cleanup EXIT
 
+# Validate all PHP object schemas
 for file in schemas/*.json
 do
 	validate_schema "$file"
 done
 
+# Disallow additional root properties in all REST API schemas (via unevaluatedProperties)
+# Disallow additional properties in the _embedded field in all REST API schemas
 for file in schemas/rest-api/*.json
 do
 	if [[ "${IGNORE_FILES[*]}" =~ "${file}" ]]
@@ -66,11 +74,12 @@ do
 	modify_schema "$file" '.properties._embedded += { "additionalProperties": false }' '.properties._embedded != null'
 done
 
+# Validation for REST API collections:
 for file in schemas/rest-api/collections/*.json
 do
 	validate_schema "$file"
 done
 
-# Validation for REST API entities that don't have a collection:
+# Validation for REST API entities that don't have a directly corresponding collection:
 validate_schema schemas/rest-api/global-style-variation.json
 validate_schema schemas/rest-api/global-style-config.json