some documentation and renamed avg to average