Introducing namespace cudaq_internal

[Renaud-K]

It occurred to me that under this proposal, it is still not quite clear to users whether they are accessing internal functionality or not. There is the possibility that internal headers are included transitively. In this case nothing can really prevent a user from using an internal class. For instance:

cudaq::compiler::Compiler c;

I believe this means that we need to introduce a cudaq_internal namespace along with the cudaq_internal root for header files.
This is what this PR is proposing.

Along with it, I am adding guidelines from the LLVM coding standard which are relevant.

[schweitzpgi]

We had already settled on a namespace of cudaq::detail for "internal use only" artifacts.

I think @khalatepradnya had a PR to standardize that once upon a time, and there are all manner of "alternative spellings" IIRC. internal, __internal__, detail, details, my_dog_fido, ...

[khalatepradnya]

We had already settled on a namespace of cudaq::detail for "internal use only" artifacts.

I think @khalatepradnya had a PR to standardize that once upon a time, and there are all manner of "alternative spellings" IIRC. internal, __internal__, detail, details, my_dog_fido, ...

It was this PR #2946.
Unfortunately, it was nixed owing to some incoming refactoring...

[Renaud-K]

detail is a sub namespace for private implementations. I don't think it is suited here because although the modules are internal, they do have an externally facing interface.
There are 3 levels of API:

1. private (detail or anonymous)
2. internal public in the cmake sense (cudaq_internal::compiler)
3. user facing (cudaq::ptsb)