fix up gtk-doc comments

fewer warnings now, phew
start unboxing returns from Python