Yes, we need good documentation.
The API should not imply whether to use `free()` or `delete[]`, but it should imply that the  user is responsible for releasing the returned buffer.
And the documentation should explicitly say: "The user should release the returned buffer by calling `free()` (or `delete[]`)"