document and add defaults