Improve WebApi documentation

[gowthamrao]

Current WebApi documentation here is sparse. Improving documentation requires updating the comments in the corresponding java code. The documentation is generated from the comments. Lack of comments makes documentation sparse.

We need to add comments to the WebApi java code. This comments should help with improving documentation for both

• REST endpoints autogenerated documentation
• ROhdsiWebApi R package

Related issues
#686
#533
#185
#197
#34

[anthonysena]

This relates to the JavaDoc comments that are compiled using miredot.

[anthonysena]

Instructions WebAPI REST endpoint documentation

Let's use this issue to track which parts of the API people plan to work on. I'll provide some instructions here on how to collaborate on this work via the OHDSI Teams channel and GitHub.

Getting started

Make sure you have access to the OHDSI MS Teams channel. To request access, use the form here. On October 3-4, we'll organize ourselves into teams to tackle documenting different parts of the WebAPI code. Don't worry if you are unsure of how to do this - that is why we'll have the MS Teams channel and we'll organize ourselves to help those that want to contribute.

MS Teams

I've set up a new channel on the OHDSI MS Teams site: Working Group - ATLAS/WebAPI. We can use this site to collaborate in real time, ask questions and meet when needed. More details will be posted to that channel.

GitHub

We will use the branch: https://github.com/OHDSI/WebAPI/tree/issue-1203-documentation as our "root" documentation branch. This branch contains some contributions from @ablack3, @chrisknoll and myself that show some basics on how to add comments to each of the endpoints.

To get started: fork the GitHub repo (documentation on how to do that here), switch to the issue-1203-documentation branch and make a new branch for your work. The branch can be named whatever makes sense to you. If you are working in a team, one person can make the fork, collect the updates and commit them to their branch. When the work is done, file a pull request and make sure the target branch on WebAPI is the issue-1203-documentation branch.

Endpoints

We are managing the list of end-points that require documentation in the following GitHub project: https://github.com/orgs/OHDSI/projects/10. Please update this project with any/all endpoints in progress.

[anthonysena]

I plan to take on the estimation and prediction end-points for those that want to join me.