docs(dav): clarify CalDAV object backend contracts

[joshtrichards]

• Resolves: #

Summary

Fix inaccuracies in and clarify the documentation and return type for calendar object retrieval methods in CalDavBackend.

The existing docblocks combine inherited SabreDAV guidance with implementation-specific behavior. This makes important differences between the single-object, multi-object, limited-field, and collection methods difficult to determine.

The updated documentation describes the observable behavior without duplicating the complete array shapes, reducing the risk of future documentation drift.

Changes

• Clarify that getCalendarObjects() returns metadata only and excludes soft-deleted objects.
• Document the UID-keyed result behavior of getLimitedCalendarObjects().
• Clarify that getCalendarObject() includes calendardata and may return soft-deleted objects.
• Add the native ?array return type to getCalendarObject().
• Add setMaxResults(1) to getCalendarObject() to document intent.
• Clarify that getMultipleCalendarObjects() performs a bulk lookup, chunks URI parameters, excludes soft-deleted objects, and does not guarantee input ordering.
• Remove or replace generic Sabre backend wording where it does not accurately describe the concrete implementation.

TODO

• ...

Checklist

• Code is properly formatted
• Sign-off message is added to all commits
• Tests (unit, integration, api and/or acceptance) are included
• Screenshots before/after for front-end changes
• Documentation (manuals or wiki) has been updated or is not required
• Backports requested where applicable (ex: critical bugfixes)
• Labels added where applicable (ex: bug/enhancement, 3. to review, feature component)
• Milestone added for target branch/version (ex: 32.x for stable32)

AI (if applicable)

• The content of this PR was partly or fully generated using AI