updated magic method docs with optional indicators