this is now clarified in the new improved doc strings :)