add documentation of blocks to methods; add nil default values