updated function header documentation using javadoc styling. inline comments have been preserved.