Ouch that is confusing. And no, I haven't added these details to documentation yet. This is a bit of an issue at the moment, having everything return in one format is the right thing to do.

Will be addressing this in the near future - thanks!