documented average function