simplification/re-styling API and docstring text

[yck011522]

          As a general comment not related to your PR in particular, but since you are changing this part, it seems fair to mention: perhaps it would be good to run the whole resulting text over chatgpt for a simplification/re-styling, because it feels like now it's pretty fragmented after several years of adding/editing little parts here and there.

Originally posted by @gonzalocasas in #390 (comment)