Update subst docstrings and minor formatting

This is a no-code change (1) - addition or modification of docstrings,
adding blank lines for readability, fixing spacing between code and
comment, and a few typing annotations.

1. there are a few instances of else dropped or elif turned to if
when the previous block ended with return or raise.  Those are
*technically* code changes, but have no behavioral effect.

Signed-off-by: Mats Wichmann <mats@linux.com>

Author: mwichmann