add documentation and nomenclature remarks