 }
 
 /**
- * Internal function
+ * Internal function.
+ * Create a new record in the database or update it if it already exists.
+ * Also set associations and run all related callbacks.
+ * Called from the save function above (inside a transaction).
  */
 public boolean function $save(
 	required any parameterize,

		persisted=arguments.persisted,
		properties=arguments.properties,
		row=arguments.row,
		useFilterLists=(!arguments.persisted)
	);

	// If the object should be persisted, call afterFind, else call afterNew.
	if ((arguments.persisted && local.rv.$callback("afterFind", arguments.callbacks)) || (!arguments.persisted && local.rv.$callback("afterNew", arguments.callbacks))) {
		local.rv.$callback("afterInitialization", arguments.callbacks);
	}


 * Property names and values can be passed in either using named arguments or as a struct to the `properties` argument.
 *
 * ```
 * // Create a new author in memory (not saved to the database).
 * newAuthor = model("author").new();
 *
 * // Create a new author based on properties in a struct.
 * newAuthor = model("author").new(params.authorStruct);
 *
 * // Create a new author by passing in named arguments.
 * newAuthor = model("author").new(firstName="John", lastName="Doe");
 *
 * // If you have a `hasOne` or `hasMany` association setup from `customer` to `order` you can do a scoped call (the `newOrder` method below will call `model("order").new(customerId=aCustomer.id)` internally).
 * aCustomer = model("customer").findByKey(params.customerId);
 * anOrder = aCustomer.newOrder(shipping=params.shipping);
 * ```
