document __init__

This fixes #8923.   @vtjnash, @JeffBezanson, please look over the text to make sure that it is accurate.

cc: @timholy 
And I think this should be two colons.