document __init__

This fixes #8923.   @vtjnash, @JeffBezanson, please look over the text to make sure that it is accurate.

cc: @timholy