docs(api): validate Model Configuration section (run 25476347078) (wheels-dev#2461)

Co-authored-by: wheels-docs-validator[bot] <wheels-docs-validator@users.noreply.github.com>

Author: github-actions[bot]

tools/docs-validation/state.json

@@ -11,6 +11,7 @@ component {
 	 * @foreignKey Foreign key property name (usually not needed if you follow Wheels conventions since the foreign key name will be deduced from the `name` argument).
 	 * @joinKey Column name to join to if not the primary key (usually not needed if you follow Wheels conventions since the join key will be the table's primary key/keys).
 	 * @joinType Use to set the join type when joining associated tables. Possible values are `inner` (for `INNER JOIN`) and `outer` (for `LEFT OUTER JOIN`).
+	 * @polymorphic Set to `true` to declare a polymorphic `belongsTo` association. The foreign key defaults to `{name}Id` and a `{name}Type` column is used to store the owning model name at runtime.
 	 */
 	public void function belongsTo(
 		required string name,
@@ -56,6 +57,7 @@ component {
 	 * @dependent Defines how to handle dependent model objects when you delete an object from this model. `delete` / `deleteAll` deletes the record(s) (`deleteAll` bypasses object instantiation). `remove` / `removeAll` sets the forein key field(s) to `NULL` (`removeAll` bypasses object instantiation).
 	 * @shortcut Set this argument to create an additional dynamic method that gets the object(s) from the other side of a many-to-many association.
 	 * @through Set this argument if you need to override Wheels conventions when using the `shortcut` argument. Accepts a list of two association names representing the chain from the opposite side of the many-to-many relationship to this model.
+	 * @as Set this argument to declare a polymorphic `hasMany` association. The child model stores the parent type in a `{as}Type` column alongside the foreign key `{as}Id`.
 	 */
 	public void function hasMany(
 		required string name,
@@ -111,6 +113,7 @@ component {
 	 * @joinKey [see:belongsTo].
 	 * @joinType [see:belongsTo].
 	 * @dependent [see:hasMany].
+	 * @as Set this argument to declare a polymorphic `hasOne` association. The child model stores the parent type in a `{as}Type` column alongside the foreign key `{as}Id`.
 	 */
 	public void function hasOne(
 		required string name,

vendor/wheels/model/associations.cfc

@@ -1,4 +1,10 @@
-// Make `isActive` the only property that can be set through mass assignment operations like `updateAll()`.
+// 1. Allow only `isActive` to be set through mass assignment (e.g. `updateAll()`, `new()`, `update()`).
 config() {
 	accessibleProperties("isActive");
 }
+
+// 2. Allow a comma-delimited list of properties to be set through mass assignment.
+//    Any property not in this list is silently ignored when set via mass assignment.
+config() {
+	accessibleProperties("firstName,lastName,email");
+}

vendor/wheels/public/docs/reference/model/accessibleproperties.txt

@@ -1,2 +1,16 @@
-// Instruct CFWheels to call the `fixObj` method after an object has been created.
-afterCreate("fixObj");
+// 1. Register a single method to run after an object is created
+// In models/User.cfc
+component extends="Model" {
+    function config() {
+        afterCreate("sendWelcomeEmail");
+    }
+    private function sendWelcomeEmail() {
+        // send email to this.email
+    }
+}
+
+// 2. Register multiple methods by passing a comma-delimited list
+afterCreate("updateCache,notifyAdmin");
+
+// 3. Register using the named `methods` argument
+afterCreate(methods="syncToExternalApi");

vendor/wheels/public/docs/reference/model/aftercreate.txt

@@ -1,2 +1,12 @@
-// Instruct CFWheels to call the `fixObj` method after an object has been deleted.
-afterDelete("fixObj");
+// 1. Call a single method after an object is deleted
+// In models/Order.cfc
+afterDelete("notifyWarehouse");
+
+// 2. Call multiple methods after an object is deleted (comma-separated list)
+// In models/User.cfc
+afterDelete("removeFromSearchIndex,clearCachedData");
+
+// 3. Register several after-delete callbacks individually for clarity
+// In models/Article.cfc
+afterDelete("logDeletion");
+afterDelete("cleanupAttachments");

vendor/wheels/public/docs/reference/model/afterdelete.txt

@@ -1,9 +1,29 @@
-// Instruct CFWheels to call the `setTime` method after getting objects or records with one of the finder methods.
+// 1. Register a single callback method to run after records are fetched
+// In models/User.cfc
 config() {
-	afterFind("setTime");
+	afterFind("setFetchedAt");
 }
 
-function setTime(){
+// The callback receives each row's columns as arguments; return the struct to modify the record.
+function setFetchedAt() {
 	arguments.fetchedAt = Now();
 	return arguments;
 }
+
+// 2. Format a column value after a find (works for both query rows and objects)
+// In models/Product.cfc
+config() {
+	afterFind("formatPrice");
+}
+
+function formatPrice() {
+	if (StructKeyExists(arguments, "price")) {
+		arguments.price = DollarFormat(arguments.price);
+	}
+	return arguments;
+}
+
+// 3. Register multiple callback methods as a comma-delimited list
+config() {
+	afterFind("setFetchedAt,formatPrice");
+}

vendor/wheels/public/docs/reference/model/afterfind.txt

@@ -1,2 +1,5 @@
-// Instruct CFWheels to call the `fixObj` method after an object has been initialized (i.e. after creating it or fetching it with a finder method).
+// 1. Call a single method after any object is initialized (whether new or fetched from the database)
 afterInitialization("fixObj");
+
+// 2. Call multiple methods after initialization by passing a comma-delimited list
+afterInitialization("setDefaults,fixObj");

vendor/wheels/public/docs/reference/model/afterinitialization.txt

@@ -1,2 +1,17 @@
-// Instruct CFWheels to call the `fixObj` method after a new object has been created.
-afterNew("fixObj");
+// 1. Call a single method after a new object is initialized
+// In models/User.cfc
+component extends="Model" {
+    function config() {
+        afterNew("setDefaults");
+    }
+    private function setDefaults() {
+        this.role = "member";
+        this.active = true;
+    }
+}
+
+// 2. Call multiple methods after a new object is initialized (comma-delimited list)
+afterNew("setDefaults,generateToken");
+
+// 3. Use the `method` argument alias instead of `methods`
+afterNew(method="setDefaults");

vendor/wheels/public/docs/reference/model/afternew.txt

@@ -1,2 +1,26 @@
-// Instruct CFWheels to call the `fixObj` method after an object has been saved.
-afterSave("fixObj");
+// 1. Register a single callback method to run after an object is saved (both create and update)
+// In models/User.cfc
+component extends="Model" {
+    function config() {
+        afterSave("sendWelcomeEmail");
+    }
+
+    private function sendWelcomeEmail() {
+        // called automatically each time a User is saved
+    }
+}
+
+// 2. Register multiple callback methods using a comma-delimited list
+component extends="Model" {
+    function config() {
+        afterSave("updateSearchIndex,notifyAdmins");
+    }
+}
+
+// 3. Register multiple callbacks by calling afterSave() more than once
+component extends="Model" {
+    function config() {
+        afterSave("updateSearchIndex");
+        afterSave("notifyAdmins");
+    }
+}

vendor/wheels/public/docs/reference/model/aftersave.txt

@@ -1,2 +1,16 @@
-// Instruct CFWheels to call the `fixObj` method after an object has been updated.
-afterUpdate("fixObj");
+// 1. Register a single method to run after an object is updated
+// In models/User.cfc
+component extends="Model" {
+    function config() {
+        afterUpdate("clearCache");
+    }
+    private function clearCache() {
+        // invalidate cached data for this user
+    }
+}
+
+// 2. Register multiple methods by passing a comma-delimited list
+afterUpdate("clearCache,notifyAuditLog");
+
+// 3. Register using the named `methods` argument
+afterUpdate(methods="syncToSearchIndex");