document __init__

This fixes #8923.   @vtjnash, @JeffBezanson, please look over the text to make sure that it is accurate.

cc: @timholy 
Seems like it does. Fixed in 9743a995ad0ea1