Describe the task
The documentation provided in the form of README.md seems inadequate in terms of getting started with the Annotator on a new project.
Expected behavior
Follow the steps listed on the readme and successfully get the annotations applied on your module.
Actual behavior
Need to do a lot of hit and trials, jump from one page to another, just to get hit by error after error and try to resolve them manually.
I am posting a list of questions which when answered could help spruce up the Readme or can be added to a GettingStarted.md or Installation.md file so that people don't have to spend so much time going through the process of just getting this project to work.
[ ] Installation
It would be nice to provide a cURL or wget command to just pull the jar from maven. Like so
I'll leave the format of the command to the authors to decide. You could either have the latest version hardcoded so that it is easily copy/pasteable OR to have a placeholder that says {version-code-here} which the user then needs to manually substitute.
[ ] Fix Broken link to AnnotatorScanner
AnnotatorScanner checker must be activated with version >= 1.3.6, see more about AnnotatorScanner [here](https://github.com/ucr-riple/NullAwayAnnotator/blob/type-annotator-scanner/README.md).
[ ] nullaway and scanner configuration file templates or schemas missing
The guide mentions that these files do not need to be created during the initial project setup. But in the very next paragraph the user is asked to provide the path to these files.
This feels confusing. One can touch these files on the command line but what should they contain? I couldn't get the script to create these files for me so I have been guessing the schema for these XML files based on the source code in the project but that didn't help much.
So can we provide some templates for these files that one can just copy/paste and get started?
[ ] Annotator jar hides all the build output which makes debugging hard
So the -bc command hides all the output that would be otherwise logged by gradle. One tip we could add here is to forward the standard output of gradle build to stderr by adding 1>&2 at the end of the build command. This makes debugging a lot easier, especially when you are getting started with this project.
[ ] config.json removed from the readme file
In the earlier versions I saw a config file being provided and passed into the jar to manage the configurations easily, is there a reason why it was removed?
[ ] template command missing required arguments so the purpose of the command fails because again it cannot be simply copy/pasted
The template command is missing -cn argument which is mentioned as must provide arg. We should update in the template command.
Happy to submit a PR if the issues and their corresponding suggestions seem useful for maintainers and adopters.
P.S. - I am trying to integrate this in a project myself with not much luck so far. So answers to some of the questions above could also help me unblock myself.
Describe the task The documentation provided in the form of README.md seems inadequate in terms of getting started with the Annotator on a new project.
Expected behavior Follow the steps listed on the readme and successfully get the annotations applied on your module.
Actual behavior Need to do a lot of hit and trials, jump from one page to another, just to get hit by error after error and try to resolve them manually.
I am posting a list of questions which when answered could help spruce up the Readme or can be added to a GettingStarted.md or Installation.md file so that people don't have to spend so much time going through the process of just getting this project to work.
cURLorwgetcommand to just pull the jar from maven. Like soOR
I'll leave the format of the command to the authors to decide. You could either have the latest version hardcoded so that it is easily copy/pasteable OR to have a placeholder that says {version-code-here} which the user then needs to manually substitute.
[ ] Fix Broken link to
AnnotatorScanner[ ] nullaway and scanner configuration file templates or schemas missing
The guide mentions that these files do not need to be created during the initial project setup. But in the very next paragraph the user is asked to provide the path to these files.
This feels confusing. One can
touchthese files on the command line but what should they contain? I couldn't get the script to create these files for me so I have been guessing the schema for these XML files based on the source code in the project but that didn't help much.So can we provide some templates for these files that one can just copy/paste and get started?
So the
-bccommand hides all the output that would be otherwise logged by gradle. One tip we could add here is to forward the standard output of gradle build to stderr by adding1>&2at the end of the build command. This makes debugging a lot easier, especially when you are getting started with this project.[ ] config.json removed from the readme file In the earlier versions I saw a config file being provided and passed into the jar to manage the configurations easily, is there a reason why it was removed?
[ ] template command missing required arguments so the purpose of the command fails because again it cannot be simply copy/pasted
The template command is missing
-cnargument which is mentioned as must provide arg. We should update in the template command.Happy to submit a PR if the issues and their corresponding suggestions seem useful for maintainers and adopters.
P.S. - I am trying to integrate this in a project myself with not much luck so far. So answers to some of the questions above could also help me unblock myself.