improve Javadoc please

[ehx-v1]

could you please add some Javadoc?
it's just that it's a bit inconvenient having to look through the entire code for getting an idea of what a method is doing
also, it would help me a lot with documenting my utility classes if I had some Javadoc as quick reference, especially for which conditions lead to which throw so I don't have to write a vague "thrown by methods called by this method"
btw if my comments are partly misspelled sorry, one point is that I'm German and, even though passed English C1, of course am no perfect speaker, and another is that I have a keyboard that is a bit faster than keyboards I'm used to, so some letters keep duping, I delete my duplicate letters where I find them but of course I can't spot them all

[ehx-v1]

just noticed there is some rudimentary Javadoc, which however provides little help (for an example see #231) so it would be nice if Javadoc along with time passing would get something alike the one in the JDK (even though there are some awful examples in the JDK too) ;-)

[craigtaverner]

I also love to have good javadoc. However, making it is harder than you would think. In my past I tried to write good javadoc all over the place, only to discover that it invariably became out of sync with the actual code. This is especially true of open source projects with many contributors. So these days I find most developers prioritize writing clean, readable code with descriptive method, field and variable names, instead of javadoc. And add javadoc only to the class, and most important method or two.

I could point out that the javadoc in the code I work on daily (cypher compiler inside neo4j) is much less complete than the javadoc inside neo4j spatial. This is because the team as a whole favours code clarify well above code commenting. The thinking is that if the code is not self explanatory, change the code, rather than add more comments.

I personally think a compromise can be found. Some cases are benefitted with docs, but I agree that we should be cautious and use code comments sparingly and be concise and expressive.

So I would prefer to add or edit code comments for specific cases that you identify, and not put in time to add comments extensively.

(and don't worry about your english, it is completely fine. I'm a native english speaker and know I make a bunch of mistakes, and fix them when I can, but as long as the meaning is clear some flaws are not a problem. I appreciate all your effort to explain and clarify yourself, and spelling or grammar errors are of no concern.)

[ehx-v1]

In other words, as for now one has to deal with it.