additional documentation on non-final API for my own reference