Create README for Java grammar updates

[nrmancuso]

From discussion at #10280 (comment) and elsewhere, with the new ANTLR4 grammar and visitor combination to build Checkstyle's AST, it may not be obvious to contributors how to update the grammar and create the AST. I propose that we write a guide, which will walk through the entire process form start to finish. Points of discussion here include:

1. Location of README file in repo (or wiki)?
2. Areas of visitor/grammar that may need additional explanation
3. Best practices to mention
4. ??

[nrmancuso]

1. I think it would be good to include this README in the directory where the grammar lives.
2. I would like to include more information about when to use DetailAstPair() and when create should be used compared to when createImaginary() should be used.
3. I would like to mention naming and case-style conventions used

[pbludov]

I think it should be a page in https://checkstyle.org/extending.html

[strkkk]

I think it should be a page in https://checkstyle.org/extending.html

This is mostly for 3rd-party check/filters/etc., but grammar changes cant be 3rd party, it is a core functionality.

We can start from wiki page (+link from main readme to it as must read for contributors who wants to change grammar)

[nrmancuso]

I should explain why I think that the guide should live in the main repo, and be written in markdown:

We can start from wiki page

1. I (and future non-member maintainers) are not able to edit the wiki. Even when directly editing the wiki, there is no ability for others to review and leave comments and suggestions as in a normal github pull request.
2. If the guide is in the in the main repo, it can still be linked from anywhere, and even duplicated in the wiki.
3. As new conventions and practices are developed for the grammar/visitor, it will be less likely that contributors and maintainers will add information to this guide if it is in the wiki.
4. It is easier for future contributors and maintainers to create and fix issues in specific parts of the guide if it is part of the main repo.
5. If the guide is part of main repo, we can check for broken links.
6. If the guide is part of main repo, we can check for spelling.

I think it should be a page in https://checkstyle.org/extending.html

1. Personally, I much prefer technical documentation in basic github markdown than HTML. The github markdown allows for more compact representation of the text.
2. It is easier for maintainers to edit github markdown than HTML. (maybe this is personal preference, too)
3. Having the guide written in markdown makes it easy to view in your editor while making changes to the grammar, without needing to open a browser:

Instead of having a README in the grammar directory, another option is to create a docs/ directory, as some other projects do. This may encourage future documentation efforts.

[mahfouz72]

@nrmancuso any updates here? I think it would be great to have an explanation of updating grammar and adding support for new tokens

[nrmancuso]

@nrmancuso any updates here? I think it would be great to have an explanation of updating grammar and adding support for new tokens

Hopefully I will get some time this summer :) Thanks for asking.