Explicitly clarify that AllocateQubits(N) returns a vector from 0 t…

…o N-1 in documentation (#1523)

**Context:**
In [the documentation for adding a custom
device](https://docs.pennylane.ai/projects/catalyst/en/stable/dev/custom_devices.html),
it should be specified that the `AllocateQubits` method of a custom
device should return a vector from 0 to `num_qubits-1`. Right now the
documentation makes it seem like it can just return a vector initialized
with all zeros (or whatever that particular machine's cpp default
initializes vectors to).

This can lead to confusion for external device implementors following
the guide. For example, if the vector is initialized with all zeros,
this would lead to the implementor finding
`__catalyst__rt__array_get_element_ptr_1d` always returning zero
regardless of the target wire.

**Description of the Change:**
Explicitly clarify that `AllocateQubits(N)` returns a vector from 0 to
N-1 in documentation, by
1. Doing so in the code listing
2. Adding a warning in documentation

**Benefits:**
Better documentation.

**Related GitHub Issues:** closes #1512 

[sc-84327]

doc/dev/custom_devices.rst

@@ -28,7 +28,11 @@ Additionally, all measurements will always return ``true``.
 
             auto AllocateQubit() -> QubitIdType override { return 0; }
             auto AllocateQubits(size_t num_qubits) -> std::vector<QubitIdType> override {
-                return std::vector<QubitIdType>(num_qubits);
+                std::vector<QubitIdType> qubits(num_qubits);
+                for (size_t i = 0; i < num_qubits; i++){
+                    qubits[i] = i;
+                }
+                return qubits;
             }
             [[nodiscard]] auto Zero() const -> Result override { return NULL; }
             [[nodiscard]] auto One() const -> Result override { return NULL; }
@@ -82,6 +86,12 @@ Additionally, all measurements will always return ``true``.
             void Gradient(std::vector<DataView<double, 1>> &, const std::vector<size_t> &) override {}
         };
 
+.. warning::
+
+    While the above is an empty device with all no-operations,
+    it should be noted that the semantics of the ``AllocateQubits`` method require it to return a vector from 0 to ``num_qubits-1``.
+    Devices not following this rule will not be able to properly query wire indices of the qubits.
+
 In addition to implementing the ``QuantumDevice`` class, one must implement an entry point for the
 device library with the name ``<DeviceIdentifier>Factory``, where ``DeviceIdentifier`` is used to
 uniquely identify the entry point symbol. As an example, we use the identifier ``CustomDevice``: