debt: code comments & godoc documentation