My feeling is we (developers) should be able to figure out how to use a function reliably and safely from just the signature for 95% of functions...if you can't

My feeling is we (developers) should be able to figure out how to use a function reliably and safely from just the signature for 95% of functions...if you can't then the API is badly written.