Improve docs as per guidline

[AzeemMuzammil]

Purpose

$title.

Fixes: ballerina-platform/ballerina-library#5952

Examples

Checklist

• Linked to an issue
• Updated the specification
• Updated the changelog
• Added tests
• Checked native-image compatibility

[NipunaRanasinghe]

Need to mention the supported GitHub REST API version

[NipunaRanasinghe]

@AzeemMuzammil for the examples, I prefer to have more real world examples which usually consist of few API usages.

e.g: Here are some examples that involve 2-3 REST API calls related to Pull Requests, Issues, and Repository operations:

1. Pull Request Creation and Review:

   • Scenario: Automatically create a pull request for a feature branch and assign reviewers based on specific criteria.
   • API Calls:
     1. Create Pull Request: Use the POST /repos/{owner}/{repo}/pulls endpoint to create a new pull request from a feature branch to the main branch.
     2. Get Reviewers: Use the GET /repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers endpoint to retrieve the current list of requested reviewers for the newly created pull request.
     3. Add Reviewers: Use the POST /repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers endpoint to add additional reviewers to the pull request based on predefined criteria.

2. Issue Management:

   • Scenario: Automatically create an issue for a bug report submitted via a web form and assign it to the appropriate team member for triage.
   • API Calls:
     1. Create Issue: Use the POST /repos/{owner}/{repo}/issues endpoint to create a new issue in the repository with details provided by the user.
     2. Label Issue: Use the PATCH /repos/{owner}/{repo}/issues/{issue_number} endpoint to add labels to the newly created issue based on predefined criteria.
     3. Assign Issue: Use the POST /repos/{owner}/{repo}/issues/{issue_number}/assignees endpoint to assign the issue to a specific team member responsible for triage.

3. Repository Operations:

   • Scenario: Fork a template repository, create a new repository, and populate it with initial files and configurations.
   • API Calls:
     1. Fork Repository: Use the POST /repos/{owner}/{repo}/forks endpoint to fork the template repository into the user's account.
     2. Create Repository: Use the POST /user/repos or POST /orgs/{org}/repos endpoint to create a new repository with the desired settings.
     3. Populate Repository: Use the GitHub API (e.g., uploading files, creating directories) to populate the new repository with initial files and configurations from the forked template repository.