epydoc related fixes

there are few improperly formatted comments, fix those
add checks for badly formatted comments to test-dev target
add `docs/` directory to `.gitignore` since we don't commit documentation to git...