Bluetooth: CAP: Broadcast: Add check for memory allocation for create

[Thalley]

When creating a broadcast source with
bt_cap_initiator_broadcast_audio_create there was no check if all broadcast sources were already allocated, which could cause a NULL pointer dereference.

Add a check, a test and documentation about possibly error codes of the function.

[Copilot]

Pull Request Overview

This PR adds a check in the broadcast source creation path to prevent a NULL pointer dereference when all broadcast sources are already allocated. It includes new error handling in the CAP initiator, updates to the test to verify the failure case when too many sources are allocated, and enhanced documentation in the header for the error codes that may be returned.

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
tests/bsim/bluetooth/audio/src/cap_initiator_broadcast_test.c	Updates the test to use an array of broadcast source pointers and verifies that creating more than the allowable sources returns -ENOMEM.
subsys/bluetooth/audio/cap_initiator.c	Initializes the output pointer, iterates properly over available sources, and returns appropriate error codes based on the error from the lower-level create call.
include/zephyr/bluetooth/audio/cap.h	Enhances the API documentation with detailed error codes for failure scenarios.