I agree. I don't like them, I even delete keyword.txt from other libraries. The problem I have with them is all keyword files are loaded, no matter if you use the library or not. So even if it's not part of the library you use if might get highlighted because it's a keyword of another library. For example, if you have (the excellent) u8g2 library installed but don't use it something like
Serial.drawDisc()
get's highlighted as if it would be valid code.
For libraries I release I generate documentation with Doxygen. Available online (GitHub) and in the "doc" folder of the library.