Skip to content

Commit 15a9418

Browse files
stloydstloyd
committed
Extend some docs
1 parent 2e75407 commit 15a9418

File tree

10 files changed

+249
-72
lines changed

10 files changed

+249
-72
lines changed

‎doc/index.md

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,17 @@
11
Navigation
22
==========
33

4-
API list:
5-
4+
APIs:
65
* [Commits](commits.md)
76
* [Gists](gists.md)
87
* [Issues](issues.md)
8+
* [Comments](issue/comments.md)
9+
* [Labels](issue/labels.md)
10+
* [Organization](organization.md)
11+
* [Members](organization/members.md)
12+
* [Teams](organization/teams.md)
913
* [Pull Requests](pull_requests.md)
14+
* [Comments](pull_request/comments.md)
1015
* [Repositories](repos.md)
1116
* [Users](users.md)
1217

‎doc/issue/comments.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
## Issues / Comments API
2+
[Back to the "Issues API"](../issues.md) | [Back to the navigation](index.md)
3+
4+
Wraps [GitHub Issue Comments API](http://developer.github.com/v3/issues/comments/).
5+
6+
### List an issue comments
7+
8+
```php
9+
<?php
10+
11+
$comments = $client->api('issue')->comments()->all('KnpLabs', 'php-github-api', 4);
12+
```
13+
14+
List an issue comments by username, repo and issue number.
15+
Returns an array of issues.
16+
17+
### Add a comment on an issue
18+
19+
> **Note:**
20+
> New comments are assigned to the authenticated user.
21+
22+
> Requires authentication.
23+
24+
```php
25+
<?php
26+
27+
$client->authenticate();
28+
$client->api('issue')->comments()->create('KnpLabs', 'php-github-api', 4, array('body' => 'My new comment'));
29+
```
30+
31+
Add a comment to the issue by username, repo and issue number and array with comment data: `body`
32+
and optionally `title`.

‎doc/issue/labels.md

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
## Issues / Labels API
2+
[Back to the "Issues API"](../issues.md) | [Back to the navigation](index.md)
3+
4+
Wraps [GitHub Issue Labels API](http://developer.github.com/v3/issues/labels/).
5+
6+
### List project labels
7+
8+
```php
9+
<?php
10+
11+
$labels = $client->api('issue')->labels()->all('KnpLabs', 'php-github-api');
12+
```
13+
14+
List all project labels by username and repo.
15+
Returns an array of project labels.
16+
17+
### Add a label on an issue
18+
19+
> Requires authentication.
20+
21+
```php
22+
<?php
23+
24+
$client->authenticate();
25+
$labels = $client->api('issue')->labels()->add('KnpLabs', 'php-github-api', 4, 'label name');
26+
```
27+
28+
Add a label to the issue by username, repo, issue number label name and. If the label is not yet in
29+
the system, it will be created.
30+
Returns an array of the issue labels.
31+
32+
### Replace all labels for an issue
33+
34+
> Requires authentication.
35+
36+
```php
37+
<?php
38+
39+
$client->authenticate();
40+
$client->api('issue')->labels()->replace('KnpLabs', 'php-github-api', 4, array('new label name'));
41+
```
42+
43+
Replace a label for an issue: by username, repo, issue number and array of labels.
44+
45+
### Remove all labels fom an issue
46+
47+
> Requires authentication.
48+
49+
```php
50+
<?php
51+
52+
$client->authenticate();
53+
$client->api('issue')->labels()->replace('KnpLabs', 'php-github-api', 4);
54+
```
55+
56+
Removal of all labels for the issue by username, repo, issue number.
57+
58+
### Remove a label from an issue
59+
60+
> Requires authentication.
61+
62+
```php
63+
<?php
64+
65+
$client->authenticate();
66+
$client->api('issue')->labels()->remove('KnpLabs', 'php-github-api', 4, 'label name');
67+
```
68+
69+
Remove a label from the issue by username, repo, issue number and label name.

‎doc/issues.md

Lines changed: 17 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,11 @@
22
[Back to the navigation](index.md)
33

44
Listing issues, searching, editing and closing your projects issues.
5-
Wrap [GitHub Issue API](http://developer.github.com/v3/issues/).
5+
Wraps [GitHub Issue API](http://developer.github.com/v3/issues/).
6+
7+
Additional APIs:
8+
* [Comments](issue/comments.md)
9+
* [Labels](issue/labels.md)
610

711
### List issues in a project
812

@@ -36,113 +40,60 @@ Returns an array of information about the issue.
3640

3741
### Open a new issue
3842

43+
> Requires authentication.
44+
3945
```php
4046
<?php
4147

4248
$client->authenticate();
4349
$client->api('issue')->create('KnpLabs', 'php-github-api', array('title' => 'The issue title', 'body' => 'The issue body');
4450
```
4551

46-
Creates a new issue in the repo "php-github-api" of the user "KnpLabs".
47-
The issue is assigned to the authenticated user. Requires authentication.
52+
Creates a new issue in the repo "php-github-api" of the user "KnpLabs". The issue is assigned to the authenticated user.
4853
Returns an array of information about the issue.
4954

5055
### Close an issue
5156

57+
> Requires authentication.
58+
5259
```php
5360
<?php
5461

5562
$client->authenticate();
5663
$client->api('issue')->update('KnpLabs', 'php-github-api', 4, array('state' => 'closed'));
5764
```
5865

59-
Closes the fourth issue of the repo "php-github-api" of the user "KnpLabs". Requires authentication.
66+
Closes the fourth issue of the repo "php-github-api" of the user "KnpLabs".
6067
Returns an array of information about the issue.
6168

6269
### Reopen an issue
6370

71+
> Requires authentication.
72+
6473
```php
6574
<?php
6675

6776
$client->authenticate();
6877
$client->api('issue')->update('KnpLabs', 'php-github-api', 4, array('state' => 'open'));
6978
```
7079

71-
Reopens the fourth issue of the repo "php-github-api" of the user "ornicar". Requires authentication.
80+
Reopens the fourth issue of the repo "php-github-api" of the user "KnpLabs".
7281
Returns an array of information about the issue.
7382

7483
### Update an issue
7584

85+
> Requires authentication.
86+
7687
```php
7788
<?php
7889

7990
$client->authenticate();
8091
$client->api('issue')->update('KnpLabs', 'php-github-api', 4, array('body' => 'The new issue body'));
8192
```
8293

83-
Updates the fourth issue of the repo "php-github-api" of the user "KnpLabs". Requires authentication.
84-
Available attributes are title and body.
94+
Updates the fourth issue of the repo "php-github-api" of the user "KnpLabs". Available attributes are title and body.
8595
Returns an array of information about the issue.
8696

87-
### List an issue comments
88-
89-
```php
90-
<?php
91-
92-
$comments = $client->api('issue')->comments()->all('KnpLabs', 'php-github-api', 4);
93-
```
94-
95-
List an issue comments by username, repo and issue number.
96-
Returns an array of issues.
97-
98-
### Add a comment on an issue
99-
100-
```php
101-
<?php
102-
103-
$client->authenticate();
104-
$client->api('issue')->comments()->create('KnpLabs', 'php-github-api', 4, array('body' => 'My new comment'));
105-
```
106-
107-
Add a comment to the issue by username, repo and issue number.
108-
The comment is assigned to the authenticated user. Requires authentication.
109-
110-
### List project labels
111-
112-
```php
113-
<?php
114-
115-
$labels = $client->api('issue')->labels()->all('KnpLabs', 'php-github-api');
116-
```
117-
118-
List all project labels by username and repo.
119-
Returns an array of project labels.
120-
121-
### Add a label on an issue
122-
123-
```php
124-
<?php
125-
126-
$client->authenticate();
127-
$client->api('issue')->labels()->add('KnpLabs', 'php-github-api', 4, 'label name');
128-
```
129-
130-
Add a label to the issue by username, repo, label name and issue number. Requires authentication.
131-
If the label is not yet in the system, it will be created.
132-
Returns an array of the issue labels.
133-
134-
### Remove a label from an issue
135-
136-
```php
137-
<?php
138-
139-
$client->authenticate();
140-
$client->api('issue')->labels()->remove('KnpLabs', 'php-github-api', 4, 'label name');
141-
```
142-
143-
Remove a label from the issue by username, repo, label name and issue number. Requires authentication.
144-
Returns an array of the issue labels.
145-
14697
### Search issues matching a label
14798

14899
```php

‎doc/organization.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
## Organization API
2+
[Back to the navigation](index.md)
3+
4+
Wraps [GitHub Organization API](http://developer.github.com/v3/organization/).
5+
6+
Additional APIs:
7+
* [Members API](organization/members.md)
8+
* [Teams API](organization/teams.md)
9+
10+
To be written...

‎doc/organization/members.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
## Organization / Members API
2+
[Back to the "Organization API"](../organization.md) | [Back to the navigation](index.md)
3+
4+
Wraps [GitHub Organization Members API](http://developer.github.com/v3/organization/members/).
5+
6+
To be written...

‎doc/organization/teams.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
## Organization / Teams API
2+
[Back to the "Organization API"](../organization.md) | [Back to the navigation](index.md)
3+
4+
Wraps [GitHub Organization Teams API](http://developer.github.com/v3/organization/teams/).
5+
6+
To be written...

‎doc/pull_request/comments.md

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
## Pull Requests / Review Comments API
2+
[Back to the "Pull Requests API"](../pull_requests.md) | [Back to the navigation](index.md)
3+
4+
Review Comments are comments on a portion of the unified diff. These are separate from Commit Comments (which
5+
are applied directly to a commit, outside of the Pull Request view), and Issue Comments (which do not reference
6+
a portion of the unified diff).
7+
8+
Wraps [GitHub PR Review Comments API](http://developer.github.com/v3/pulls/comments/).
9+
10+
> **Note:**
11+
> New comments are assigned to the authenticated user.
12+
13+
### List all comments for selected pull request
14+
15+
```php
16+
<?php
17+
18+
$comments = $client->api('pull_request')->comments()->all('KnpLabs', 'php-github-api', 8);
19+
```
20+
21+
``$comments`` contains an array of review comments in selected pull-request for this repository.
22+
23+
### Show one comment
24+
25+
```php
26+
<?php
27+
28+
$comment = $client->api('pull_request')->comments()->show('KnpLabs', 'php-github-api', 15);
29+
```
30+
31+
The last parameter of this call, Review Comment ID.
32+
33+
### Populated with full details
34+
35+
> Requires authentication.
36+
37+
```php
38+
<?php
39+
40+
$client->authenticate();
41+
$comment = $client->api('pull_request')->comments()->create('KnpLabs', 'php-github-api', 8, array(
42+
'body' => 'Nice change',
43+
'commit_id' => 'da6e3879b5658908c3cdf562dacbc458675586ca',
44+
'path' => 'README.markdown',
45+
'position' => 37,
46+
'line' => 31
47+
);
48+
```
49+
50+
This returns the details of the comment.
51+
52+
### Populated as a reply to another comment
53+
54+
> Requires authentication.
55+
56+
```php
57+
<?php
58+
59+
$client->authenticate();
60+
$comment = $client->api('pull_request')->comments()->create('KnpLabs', 'php-github-api', 8, array(
61+
'body' => 'Yeah! Really nice change',
62+
'in_reply_to' => 2
63+
);
64+
```
65+
66+
This returns the details of the comment.
67+
68+
### Update comment details
69+
70+
> Requires authentication.
71+
72+
```php
73+
<?php
74+
75+
$client->authenticate();
76+
$comment = $client->api('pull_request')->comments()->update('KnpLabs', 'php-github-api', 2, array(
77+
'body' => 'Hell Yeah! Awesome change!'
78+
);
79+
```
80+
81+
This returns the details of the updated comment.
82+
83+
### Remove a review comment from an pull request
84+
85+
> Requires authentication.
86+
87+
```php
88+
<?php
89+
90+
$client->authenticate();
91+
$client->api('pull_request')->comments()->remove('KnpLabs', 'php-github-api', 2);
92+
```
93+
94+
Remove a comment from the pull request by username, repo, comment number.

‎doc/pull_requests.md

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,12 @@
11
## Pull Requests API
22
[Back to the navigation](index.md)
33

4-
Lets you list pull requests for a given repository, list one pull request in particular along with its discussion, and create a pull-request.
5-
Wraps [GitHub Pull Request API](http://developer.github.com/v3/pulls/), still tagged **BETA**. All methods are described there.
4+
Additional APIs:
5+
* [Review Comments](pull_request/comments.md)
6+
7+
Lets you list pull requests for a given repository, list one pull request in particular along
8+
with its discussion, and create a pull-request.
9+
Wraps [GitHub Pull Request API](http://developer.github.com/v3/pulls/).
610

711
### List all pull requests, per repository
812

0 commit comments

Comments
 (0)