The documentation surely needs some work. I also have trouble sometimes figuring how to use the API, but (3D) raycasting is quite self-explanatory (this is C#):
You have to pass two objects: PhysicsRaycastResult as reference, which is going to contain the resulting data, and Ray which just contains two 3D vectors (origin and direction). After the cast is performed the object that was hit is in the PhysicsRaycastResult.Body property (null if none).
I don't think there's scripting API to perform 2D casts yet, but I could be wrong here.
For a complete beginner I think Atomic could be a bit confusing, but the API is quite standard in my opinion, maybe there's a couple of unusual namings but nothing an intermediate developer can't figure out, beginners can count on our amazing community for help . We surely need more tutorials and better documentation. We have some ongoing efforts on that, including our Wiki on GitHub.