Yea, I agree that docs shouldn't use auto. It's real pain in ...I am fine with auto in code examples but in function/method description the returned type should be clearly pointed out.
I personally only try to use auto where the type is unambiguous. For example, if I'm calling a function in the same module, I'll still write the type out -- a little work for more clarity. Where auto shines of course is redundant type specification.
