let's add some doxygen comments about the difference between these two methods