adding documentation, consting where it is obvious, removed silly calloc call