Clarify that create returns a separate entity

[elpete]

Addresses #245

Issue review

This is a useful and accurate documentation improvement. BaseEntity.create() is a factory-style convenience method: it calls newEntity(), fills that new instance, saves it, and returns it. Calling create() does not mutate or load the receiver. That distinction is easy to miss and can leave application variables pointing at an unloaded entity.

Recommendation: 9/10 — document explicitly.

Reasons for:

• misunderstanding the return value can produce subtle application bugs
• the implementation has always made the separate-instance behavior explicit, but the user-facing wording does not
• a short assignment example makes the safe usage obvious

Tradeoffs:

• the GitBook page itself is maintained in the separate ortus-docs/quick-docs repository on version branches; that repository has no next branch
• this PR therefore updates Quick’s source/API documentation and locks the behavior down in next, while the same wording should be carried to the versioned GitBook source when documentation is published

Implementation

The BaseEntity.create() documentation now states that it always creates and returns a separate instance, does not mutate the receiver, and shows assigning the return value.

A public API integration test demonstrates the exact concern from the issue:

• the original entity remains unloaded and has no username
• the returned entity is loaded and has the created username

No runtime behavior was changed.

Validation

• focused CreateSpec: 4 passed, 0 failed, 0 errors
• full Lucee 6 suite using qb 14.0.0-beta.3: 496 passed, 0 failed, 0 errors, 3 skipped
• formatter completed
• git diff --check passed

[elpete]

Moved to the canonical Quick documentation repository as ortus-docs/quick-docs#64.