i'd rather see these specs corrected if they are wrong. as someone who wrote these functions and forgets what they return regularly the spec, as stands, is extremely helpful.