dropped the list_only param, not natural
made abstract methods explicit and added docs to guide implementation