introducing doc strings where appropriate