Barrapunto

Hombre, pero ahí te estas saliendo de la documentación de código. Una cosa es el análisis de porque decides hacerlo de una forma y no de otra y cosa bien distinta es documentar el código. Para entender el código poco importará si es el método más eficiente o una explicación acerca de porque utilizas unas determinadas normas.
Si yo hago una función que resuelva ecuaciones tendré que comentar el código propiamente dicho. Poner como comentario todas las demostraciones matemáticas relacionadas con la resolución ecuaciones no es, precisamente, nada útil.
Su lugar, en todo caso, sería en la documentación de análisis o en algún anexo, nunca en medio del código.