fix doco and handle optional properties