document traits and type hint return values