Worst Phobos documentation evar!

[bachmeier via Digitalmars-d]

On Sunday, 28 December 2014 at 17:22:50 UTC, Kiith-Sa wrote:
>> That's a good idea. I propose rule #1: Under no circumstances 
>> will auto be allowed in any examples. The compiler should even 
>> reject files in which they appear. One of the most frustrating 
>> things is to read documentation with type T (completely 
>> uninformative) followed by an example with auto.
>
> Doesn't work with Voldemort types, stupid with LongClassName a 
> = new LongClassName(long, parameter, list). Use your brain, not 
> "under no circumstances" rules, when writing documentation. 
> Same as Params:/Returns: - they may not be useful for trivial 
> functions but are very useful with more complex ones. Again, 
> use your brain - "Will someone reading this thing I'm writing 
> here have any actual idea about how to use this function?"

So you're arguing that the existing documentation was written by 
folks not using their brains? "Use your brain" doesn't work and 
that is the reason rules are necessary. Same thing for "Will 
someone reading this thing I'm writing here have any actual idea 
about how to use this function?" Everyone has their own 
definition of what can be understood. The person that wrote the 
documentation that started this thread evidently thought the 
explanation was sufficient. Without rules you have nothing.