improve code documentation

Many warnings about the linter need to be fixed