add docs for *By method