documenting `by` decorator