some more verbose doc notes in 2aab3f