octokit 1.17.1 → 1.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -68,6 +68,31 @@ module Octokit
68
68
  post("repos/#{Repository.new(repo)}/pulls", options.merge(pull))
69
69
  end
70
70
 
71
+ # Update a pull request
72
+ #
73
+ # @param repo [String, Hash, Repository] A GitHub repository.
74
+ # @param id [Integer] Id of pull request to update.
75
+ # @param title [String] Title for the pull request.
76
+ # @param body [String] Body content for pull request. Supports GFM.
77
+ # @param state [String] State of the pull request. `open` or `closed`.
78
+ # @return [Hashie::Mash] Hash representing updated pull request.
79
+ # @see http://developer.github.com/v3/pulls/#update-a-pull-request
80
+ # @example
81
+ # @client.update_pull_request('pengwynn/octokit', 67, 'new title', 'updated body', 'closed')
82
+ # @example Passing nil for optional attributes to update specific attributes.
83
+ # @client.update_pull_request('pengwynn/octokit', 67, nil, nil, 'open')
84
+ # @example Empty body by passing empty string
85
+ # @client.update_pull_request('pengwynn/octokit', 67, nil, '')
86
+ def update_pull_request(repo, id, title=nil, body=nil, state=nil, options={})
87
+ options.merge!({
88
+ :title => title,
89
+ :body => body,
90
+ :state => state
91
+ })
92
+ options.reject! { |_, value| value.nil? }
93
+ post("repos/#{Repository.new repo}/pulls/#{id}", options, 3)
94
+ end
95
+
71
96
 
72
97
  # List commits on a pull request
73
98
  #
@@ -186,73 +186,254 @@ module Octokit
186
186
  update_repository repo, options.merge({ :private => false })
187
187
  end
188
188
 
189
+ # Get deploy keys on a repo
190
+ #
191
+ # Requires authenticated client.
192
+ #
193
+ # @param repo [String, Hash, Repository] A GitHub repository
194
+ # @return [Array<Hashie::Mash>] Array of hashes representing deploy keys.
195
+ # @see Octokit::Client
196
+ # @see http://developer.github.com/v3/repos/keys/#get
197
+ # @example
198
+ # @client.deploy_keys('pengwynn/octokit')
199
+ # @example
200
+ # @client.list_deploy_keys('pengwynn/octokit')
189
201
  def deploy_keys(repo, options={})
190
202
  get "repos/#{Repository.new repo}/keys", options, 3
191
203
  end
192
204
  alias :list_deploy_keys :deploy_keys
193
205
 
206
+ # Add deploy key to a repo
207
+ #
208
+ # Requires authenticated client.
209
+ #
210
+ # @param repo [String, Hash, Repository] A GitHub repository.
211
+ # @param title [String] Title reference for the deploy key.
212
+ # @param key [String] Public key.
213
+ # @return [Hashie::Mash] Hash representing newly added key.
214
+ # @see Octokit::Client
215
+ # @see http://developer.github.com/v3/repos/keys/#create
216
+ # @example
217
+ # @client.add_deploy_key('pengwynn/octokit', 'Staging server', 'ssh-rsa AAA...')
194
218
  def add_deploy_key(repo, title, key, options={})
195
219
  post "repos/#{Repository.new repo}/keys", options.merge(:title => title, :key => key), 3
196
220
  end
197
221
 
222
+ # Remove deploy key from a repo
223
+ #
224
+ # Requires authenticated client.
225
+ #
226
+ # @param repo [String, Hash, Repository] A GitHub repository.
227
+ # @param id [Integer] Id of the deploy key to remove.
228
+ # @return [Boolean] True if key removed, false otherwise.
229
+ # @see Octokit::Client
230
+ # @see http://developer.github.com/v3/repos/keys/#delete
231
+ # @example
232
+ # @client.remove_deploy_key('pengwynn/octokit', 100000)
198
233
  def remove_deploy_key(repo, id, options={})
199
234
  delete "repos/#{Repository.new repo}/keys/#{id}", options, 3
200
235
  end
201
236
 
237
+ # List collaborators
238
+ #
239
+ # Requires authenticated client for private repos.
240
+ #
241
+ # @param repo [String, Hash, Repository] A GitHub repository.
242
+ # @return [Array<Hashie::Mash>] Array of hashes representing collaborating users.
243
+ # @see Octokit::Client
244
+ # @see http://developer.github.com/v3/repos/collaborators/#list
245
+ # @example
246
+ # Octokit.collaborators('pengwynn/octokit')
247
+ # @example
248
+ # Octokit.collabs('pengwynn/octokit')
249
+ # @example
250
+ # @client.collabs('pengwynn/octokit')
202
251
  def collaborators(repo, options={})
203
252
  get "repos/#{Repository.new repo}/collaborators", options, 3
204
253
  end
205
254
  alias :collabs :collaborators
206
255
 
256
+ # Add collaborator to repo
257
+ #
258
+ # Requires authenticated client.
259
+ #
260
+ # @param repo [String, Hash, Repository] A GitHub repository.
261
+ # @param collaborator [String] Collaborator GitHub username to add.
262
+ # @return [Boolean] True if collaborator added, false otherwise.
263
+ # @see Octokit::Client
264
+ # @see http://developer.github.com/v3/repos/collaborators/#add-collaborator
265
+ # @example
266
+ # @client.add_collaborator('pengwynn/octokit', 'holman')
267
+ # @example
268
+ # @client.add_collab('pengwynn/octokit', 'holman')
207
269
  def add_collaborator(repo, collaborator, options={})
208
270
  put "repos/#{Repository.new repo}/collaborators/#{collaborator}", options, 3
209
271
  end
210
272
  alias :add_collab :add_collaborator
211
273
 
274
+ # Remove collaborator from repo.
275
+ #
276
+ # Requires authenticated client.
277
+ #
278
+ # @param repo [String, Hash, Repository] A GitHub repository.
279
+ # @param collaborator [String] Collaborator GitHub username to remove.
280
+ # @return [Boolean] True if collaborator removed, false otherwise.
281
+ # @see Octokit::Client
282
+ # @see http://developer.github.com/v3/repos/collaborators/#remove-collaborator
283
+ # @example
284
+ # @client.remove_collaborator('pengwynn/octokit', 'holman')
285
+ # @example
286
+ # @client.remove_collab('pengwynn/octokit', 'holman')
212
287
  def remove_collaborator(repo, collaborator, options={})
213
288
  delete "repos/#{Repository.new repo}/collaborators/#{collaborator}", options, 3
214
289
  end
215
290
  alias :remove_collab :remove_collaborator
216
291
 
292
+ # List teams for a repo
293
+ #
294
+ # Requires authenticated client that is an owner or collaborator of the repo.
295
+ #
296
+ # @param repo [String, Hash, Repository] A GitHub repository.
297
+ # @return [Array<Hashie::Mash>] Array of hashes representing teams.
298
+ # @see Octokit::Client
299
+ # @see http://developer.github.com/v3/repos/#list-teams
300
+ # @example
301
+ # @client.repository_teams('octokit/pengwynn')
302
+ # @example
303
+ # @client.repo_teams('octokit/pengwynn')
304
+ # @example
305
+ # @client.teams('octokit/pengwynn')
217
306
  def repository_teams(repo, options={})
218
307
  get "repos/#{Repository.new repo}/teams", options, 3
219
308
  end
220
309
  alias :repo_teams :repository_teams
221
310
  alias :teams :repository_teams
222
311
 
312
+ # List contributors to a repo
313
+ #
314
+ # Requires authenticated client for private repos.
315
+ #
316
+ # @param repo [String, Hash, Repository] A GitHub repository.
317
+ # @param anon [Boolean] Set true to include annonymous contributors.
318
+ # @return [Array<Hashie::Mash>] Array of hashes representing users.
319
+ # @see Octokit::Client
320
+ # @see http://developer.github.com/v3/repos/#list-contributors
321
+ # @example
322
+ # Octokit.contributors('pengwynn/octokit', true)
323
+ # @example
324
+ # Octokit.contribs('pengwynn/octokit')
325
+ # @example
326
+ # @client.contribs('pengwynn/octokit')
223
327
  def contributors(repo, anon=false, options={})
224
328
  get "repos/#{Repository.new repo}/contributors", options.merge(:anon => anon), 3
225
329
  end
226
330
  alias :contribs :contributors
227
331
 
332
+ # List stargazers of a repo
333
+ #
334
+ # Requires authenticated client for private repos.
335
+ #
336
+ # @param repo [String, Hash, Repository] A GitHub repository.
337
+ # @return [Array<Hashie::Mash>] Array of hashes representing users.
338
+ # @see Octokit::Client
339
+ # @see http://developer.github.com/v3/repos/starring/#list-stargazers
340
+ # @example
341
+ # Octokit.stargazers('pengwynn/octokit')
342
+ # @example
343
+ # @client.stargazers('pengwynn/octokit')
228
344
  def stargazers(repo, options={})
229
345
  get "repos/#{Repository.new repo}/stargazers", options, 3
230
346
  end
231
347
 
348
+ # @deprecated Use #stargazers instead
349
+ #
350
+ # List watchers of repo.
351
+ #
352
+ # Requires authenticated client for private repos.
353
+ #
354
+ # @param repo [String, Hash, Repository] A GitHub repository.
355
+ # @return [Array<Hashie::Mash>] Array of hashes representing users.
356
+ # @see Octokit::Client::Repositories#stargazers
357
+ # @see Octokit::Client
358
+ # @see http://developer.github.com/v3/repos/watching/#list-watchers
359
+ # @example
360
+ # Octokit.watchers('pengwynn/octokit')
361
+ # @example
362
+ # @client.watchers('pengwynn/octokit')
232
363
  def watchers(repo, options={})
233
364
  get "repos/#{Repository.new repo}/watchers", options, 3
234
365
  end
235
366
 
367
+ # List forks
368
+ #
369
+ # Requires authenticated client for private repos.
370
+ #
371
+ # @param repo [String, Hash, Repository] A GitHub repository.
372
+ # @return [Array<Hashie::Mash>] Array of hashes representing repos.
373
+ # @see Octokit::Client
374
+ # @see http://developer.github.com/v3/repos/forks/#list-forks
375
+ # @example
376
+ # Octokit.forks('pengwynn/octokit')
377
+ # @example
378
+ # Octokit.network('pengwynn/octokit')
379
+ # @example
380
+ # @client.forks('pengwynn/octokit')
236
381
  def forks(repo, options={})
237
382
  get "repos/#{Repository.new repo}/forks", options, 3
238
383
  end
239
384
  alias :network :forks
240
385
 
386
+ # List languages of code in the repo.
387
+ #
388
+ # Requires authenticated client for private repos.
389
+ #
390
+ # @param repo [String, Hash, Repository] A GitHub repository.
391
+ # @return [Array<Hashie::Mash>] Array of Hashes representing languages.
392
+ # @see Octokit::Client
393
+ # @see http://developer.github.com/v3/repos/#list-languages
394
+ # @example
395
+ # Octokit.langauges('pengwynn/octokit')
396
+ # @example
397
+ # @client.languages('pengwynn/octokit')
241
398
  def languages(repo, options={})
242
399
  get "repos/#{Repository.new repo}/languages", options, 3
243
400
  end
244
401
 
402
+ # List tags
403
+ #
404
+ # Requires authenticated client for private repos.
405
+ #
406
+ # @param repo [String, Hash, Repository] A GitHub repository.
407
+ # @return [Array<Hashie::Mash>] Array of hashes representing tags.
408
+ # @see Octokit::Client
409
+ # @see http://developer.github.com/v3/repos/#list-tags
410
+ # @example
411
+ # Octokit.tags('pengwynn/octokit')
412
+ # @example
413
+ # @client.tags('pengwynn/octokit')
245
414
  def tags(repo, options={})
246
415
  get "repos/#{Repository.new repo}/tags", options, 3
247
416
  end
248
417
 
418
+ # List branches
419
+ #
420
+ # Requires authenticated client for private repos.
421
+ #
422
+ # @param repo [String, Hash, Repository] A GitHub repository.
423
+ # @return [Array<Hashie::Mash>] Array of hashes representing branches.
424
+ # @see Octokit::Client
425
+ # @see http://developer.github.com/v3/repos/#list-branches
426
+ # @example
427
+ # Octokit.branches('pengwynn/octokit')
428
+ # @example
429
+ # @client.branches('pengwynn/octokit')
249
430
  def branches(repo, options={})
250
431
  get "repos/#{Repository.new repo}/branches", options, 3
251
432
  end
252
433
 
253
434
  # Get a single branch from a repository
254
435
  #
255
- # @param repo [String, Repository, Hash] A GitHub repository
436
+ # @param repo [String, Hash, Repository] A GitHub repository.
256
437
  # @param branch [String] Branch name
257
438
  # @return [Branch] The branch requested, if it exists
258
439
  # @see http://developer.github.com/v3/repos/#get-branch
@@ -263,28 +444,139 @@ module Octokit
263
444
  end
264
445
  alias :get_branch :branch
265
446
 
447
+ # List repo hooks
448
+ #
449
+ # Requires authenticated client.
450
+ #
451
+ # @param repo [String, Hash, Repository] A GitHub repository.
452
+ # @return [Array<Hashie::Mash>] Array of hashes representing hooks.
453
+ # @see Octokit::Client
454
+ # @see http://developer.github.com/v3/repos/hooks/#list
455
+ # @example
456
+ # @client.hooks('pengwynn/octokit')
266
457
  def hooks(repo, options={})
267
458
  get "repos/#{Repository.new repo}/hooks", options, 3
268
459
  end
269
460
 
461
+ # Get single hook
462
+ #
463
+ # Requires authenticated client.
464
+ #
465
+ # @param repo [String, Hash, Repository] A GitHub repository.
466
+ # @param id [Integer] Id of the hook to get.
467
+ # @return [Hashie::Mash] Hash representing hook.
468
+ # @see Octokit::Client
469
+ # @see http://developer.github.com/v3/repos/hooks/#get-single-hook
470
+ # @example
471
+ # @client.hook('pengwynn/octokit', 100000)
270
472
  def hook(repo, id, options={})
271
473
  get "repos/#{Repository.new repo}/hooks/#{id}", options, 3
272
474
  end
273
475
 
476
+ # Create a hook
477
+ #
478
+ # Requires authenticated client.
479
+ #
480
+ # @param repo [String, Hash, Repository] A GitHub repository.
481
+ # @param name [String] The name of the service that is being called. See
482
+ # {https://api.github.com/hooks Hooks} for the possible names.
483
+ # @param config [Hash] A Hash containing key/value pairs to provide
484
+ # settings for this hook. These settings vary between the services and
485
+ # are defined in the {https://github.com/github/github-services github-services} repo.
486
+ # @option options [Array<String>] :events ('["push"]') Determines what
487
+ # events the hook is triggered for.
488
+ # @option options [Boolean] :active Determines whether the hook is
489
+ # actually triggered on pushes.
490
+ # @see Octokit::Client
491
+ # @see https://api.github.com/hooks
492
+ # @see https://github.com/github/github-services
493
+ # @see http://developer.github.com/v3/repos/hooks/#create-a-hook
494
+ # @example
495
+ # @client.create_hook(
496
+ # 'pengwynn/octokit',
497
+ # 'web',
498
+ # {
499
+ # :url => 'http://something.com/webhook',
500
+ # :content_type => 'json'
501
+ # },
502
+ # {
503
+ # :events => ['push', 'pull_request'],
504
+ # :active => true
505
+ # }
506
+ # )
274
507
  def create_hook(repo, name, config, options={})
275
508
  options = {:name => name, :config => config, :events => ["push"], :active => true}.merge(options)
276
509
  post "repos/#{Repository.new repo}/hooks", options, 3
277
510
  end
278
511
 
512
+ # Edit a hook
513
+ #
514
+ # Requires authenticated client.
515
+ #
516
+ # @param repo [String, Hash, Repository] A GitHub repository.
517
+ # @param id [Integer] Id of the hook being updated.
518
+ # @param name [String] The name of the service that is being called. See
519
+ # {https://api.github.com/hooks Hooks} for the possible names.
520
+ # @param config [Hash] A Hash containing key/value pairs to provide
521
+ # settings for this hook. These settings vary between the services and
522
+ # are defined in the {https://github.com/github/github-services github-services} repo.
523
+ # @option options [Array<String>] :events ('["push"]') Determines what
524
+ # events the hook is triggered for.
525
+ # @option options [Array<String>] :add_events Determines a list of events
526
+ # to be added to the list of events that the Hook triggers for.
527
+ # @option options [Array<String>] :remove_events Determines a list of events
528
+ # to be removed from the list of events that the Hook triggers for.
529
+ # @option options [Boolean] :active Determines whether the hook is
530
+ # actually triggered on pushes.
531
+ # @see Octokit::Client
532
+ # @see https://api.github.com/hooks
533
+ # @see https://github.com/github/github-services
534
+ # @see http://developer.github.com/v3/repos/hooks/#edit-a-hook
535
+ # @example
536
+ # @client.edit_hook(
537
+ # 'pengwynn/octokit',
538
+ # 'web',
539
+ # {
540
+ # :url => 'http://something.com/webhook',
541
+ # :content_type => 'json'
542
+ # },
543
+ # {
544
+ # :add_events => ['status'],
545
+ # :remove_events => ['pull_request'],
546
+ # :active => true
547
+ # }
548
+ # )
279
549
  def edit_hook(repo, id, name, config, options={})
280
550
  options = {:name => name, :config => config, :events => ["push"], :active => true}.merge(options)
281
551
  patch "repos/#{Repository.new repo}/hooks/#{id}", options, 3
282
552
  end
283
553
 
554
+ # Delete hook
555
+ #
556
+ # Requires authenticated client.
557
+ #
558
+ # @param repo [String, Hash, Repository] A GitHub repository.
559
+ # @param id [Integer] Id of the hook to remove.
560
+ # @return [Boolean] True if hook removed, false otherwise.
561
+ # @see Octokit::Client
562
+ # @see http://developer.github.com/v3/repos/hooks/#delete-a-hook
563
+ # @example
564
+ # @client.remove_hook('pengwynn/octokit', 1000000)
284
565
  def remove_hook(repo, id, options={})
285
566
  delete "repos/#{Repository.new repo}/hooks/#{id}", options, 3
286
567
  end
287
568
 
569
+ # Test hook
570
+ #
571
+ # Requires authenticated client.
572
+ #
573
+ # @param repo [String, Hash, Repository] A GitHub repository.
574
+ # @param id [Integer] Id of the hook to test.
575
+ # @return [nil]
576
+ # @see Octokit::Client
577
+ # @see http://developer.github.com/v3/repos/hooks/#test-a-hook
578
+ # @example
579
+ # @client.test_hook('pengwynn/octokit', 1000000)
288
580
  def test_hook(repo, id, options={})
289
581
  post "repos/#{Repository.new repo}/hooks/#{id}/test", options, 3
290
582
  end
@@ -302,6 +594,20 @@ module Octokit
302
594
  end
303
595
  alias :repo_issue_events :repository_issue_events
304
596
 
597
+ # List users available for assigning to issues.
598
+ #
599
+ # Requires authenticated client for private repos.
600
+ #
601
+ # @param repo [String, Hash, Repository] A GitHub repository.
602
+ # @returns [Array<Hashie::Mash>] Array of hashes representing users.
603
+ # @see Octokit::Client
604
+ # @see http://developer.github.com/v3/issues/assignees/#list-assignees
605
+ # @example
606
+ # Octokit.repository_assignees('pengwynn/octokit')
607
+ # @example
608
+ # Octokit.repo_assignees('pengwynn/octokit')
609
+ # @example
610
+ # @client.repository_assignees('pengwynn/octokit')
305
611
  def repository_assignees(repo, options={})
306
612
  get "repos/#{Repository.new repo}/assignees", options, 3
307
613
  end
@@ -1,7 +1,18 @@
1
1
  module Octokit
2
2
  class Client
3
+ #@todo Add support for getting a single public key by id.
4
+ # http://developer.github.com/v3/users/keys/#get-a-single-public-key
5
+ #@todo Add support for updating a public key.
6
+ # http://developer.github.com/v3/users/keys/#update-a-public-key
3
7
  module Users
4
8
 
9
+ # Search for user.
10
+ #
11
+ # @param search [String] User to search for.
12
+ # @return [Array<Hashie::Mash>] Array of hashes representing users.
13
+ # @see http://developer.github.com/v3/search/#search-users
14
+ # @example
15
+ # Octokit.search_users('pengwynn')
5
16
  def search_users(search, options={})
6
17
  get("legacy/user/search/#{search}", options, 3)['users']
7
18
  end
@@ -10,6 +21,7 @@ module Octokit
10
21
  #
11
22
  # @param user [String] A GitHub user name.
12
23
  # @return [Hashie::Mash]
24
+ # @see http://developer.github.com/v3/users/#get-a-single-user
13
25
  # @example
14
26
  # Octokit.user("sferik")
15
27
  def user(user=nil)
@@ -37,14 +49,38 @@ module Octokit
37
49
  patch("user", options, 3)
38
50
  end
39
51
 
52
+ # Get a user's followers.
53
+ #
54
+ # @param user [String] Username of the user whose list of followers you are getting.
55
+ # @return [Array<Hashie::Mash>] Array of hashes representing users followers.
56
+ # @see http://developer.github.com/v3/users/followers/#list-followers-of-a-user
57
+ # @example
58
+ # Octokit.followers('pengwynn')
40
59
  def followers(user=login, options={})
41
60
  get("users/#{user}/followers", options, 3)
42
61
  end
43
62
 
63
+ # Get list of users a user is following.
64
+ #
65
+ # @param user [String] Username of the user who you are getting the list of the people they follow.
66
+ # @return [Array<Hashie::Mash>] Array of hashes representing users a user is following.
67
+ # @see http://developer.github.com/v3/users/followers/#list-users-following-another-user
68
+ # @example
69
+ # Octokit.following('pengwynn')
44
70
  def following(user=login, options={})
45
71
  get("users/#{user}/following", options, 3)
46
72
  end
47
73
 
74
+ # Check if you are following a user.
75
+ #
76
+ # Requries an authenticated client.
77
+ #
78
+ # @param user [String] Username of the user that you want to check if you are following.
79
+ # @return [Boolean] True if you are following the user, false otherwise.
80
+ # @see Octokit::Client
81
+ # @see http://developer.github.com/v3/users/followers/#check-if-you-are-following-a-user
82
+ # @example
83
+ # @client.follows?('pengwynn')
48
84
  def follows?(*args)
49
85
  target = args.pop
50
86
  user = args.first
@@ -55,50 +91,155 @@ module Octokit
55
91
  false
56
92
  end
57
93
 
94
+ # Follow a user.
95
+ #
96
+ # Requires authenticatied client.
97
+ #
98
+ # @param user [String] Username of the user to follow.
99
+ # @return [Boolean] True if follow was successful, false otherwise.
100
+ # @see Octokit::Client
101
+ # @see http://developer.github.com/v3/users/followers/#follow-a-user
102
+ # @example
103
+ # @client.follow('holman')
58
104
  def follow(user, options={})
59
105
  put("user/following/#{user}", options, 3, true, raw=true).status == 204
60
106
  end
61
107
 
108
+ # Unfollow a user.
109
+ #
110
+ # Requires authenticated client.
111
+ #
112
+ # @param user [String] Username of the user to unfollow.
113
+ # @return [Boolean] True if unfollow was successful, false otherwise.
114
+ # @see Octokit::Client
115
+ # @see http://developer.github.com/v3/users/followers/#unfollow-a-user
116
+ # @example
117
+ # @client.unfollow('holman')
62
118
  def unfollow(user, options={})
63
119
  delete("user/following/#{user}", options, 3, true, raw=true).status == 204
64
120
  end
65
121
 
122
+ # Get list of repos starred by a user.
123
+ #
124
+ # @param user [String] Username of the user to get the list of their starred repositories.
125
+ # @return [Array<Hashie::Mash>] Array of hashes representing repositories starred by user.
126
+ # @see http://developer.github.com/v3/repos/starring/#list-repositories-being-starred
127
+ # @example
128
+ # Octokit.starred('pengwynn')
66
129
  def starred(user=login, options={})
67
130
  get("users/#{user}/starred", options, 3)
68
131
  end
69
132
 
133
+ # Check if you are starring a repo.
134
+ #
135
+ # Requires authenticated client.
136
+ #
137
+ # @param user [String] Username of repository owner.
138
+ # @param repo [String] Name of the repository.
139
+ # @return [Boolean] True if you are following the repo, false otherwise.
140
+ # @see Octokit::Client
141
+ # @see http://developer.github.com/v3/repos/starring/#check-if-you-are-starring-a-repository
142
+ # @example
143
+ # @client.starred?('pengwynn', 'octokit')
70
144
  def starred?(user, repo, options={})
71
145
  get("user/starred/#{user}/#{repo}", options, 3, true, raw=true).status == 204
72
146
  rescue Octokit::NotFound
73
147
  false
74
148
  end
75
149
 
150
+ # Get list of repos watched by a user.
151
+ #
152
+ # Legacy, using github.beta media type. Use `Users#starred` instead.
153
+ #
154
+ # @param user [String] Username of the user to get the list of repositories they are watching.
155
+ # @return [Array<Hashie::Mash>] Array of hashes representing repositories watched by user.
156
+ # @see Users#starred
157
+ # @see http://developer.github.com/v3/repos/starring/#list-stargazers
158
+ # @example
159
+ # Octokit.watched('pengwynn')
76
160
  def watched(user=login, options={})
77
161
  get("users/#{user}/watched", options, 3)
78
162
  end
79
163
 
80
- # Not yet supported: get a single key, update an existing key
81
-
164
+ # Get list of public keys for user.
165
+ #
166
+ # Requires authenticated client.
167
+ #
168
+ # @return [Array<Hashie::Mash>] Array of hashes representing public keys.
169
+ # @see Octokit::Client
170
+ # @see http://developer.github.com/v3/users/keys/#list-public-keys-for-a-user
171
+ # @example
172
+ # @client.keys
82
173
  def keys(options={})
83
174
  get("user/keys", options, 3)
84
175
  end
85
176
 
177
+ # Add public key to user account.
178
+ #
179
+ # Requires authenticated client.
180
+ #
181
+ # @param title [String] Title to give reference to the public key.
182
+ # @param key [String] Public key.
183
+ # @return [Hashie::Mash] Hash representing the newly added public key.
184
+ # @see Octokit::Client
185
+ # @see http://developer.github.com/v3/users/keys/#create-a-public-key
186
+ # @example
187
+ # @client.add_key('Personal projects key', 'ssh-rsa AAA...')
86
188
  def add_key(title, key, options={})
87
189
  post("user/keys", options.merge({:title => title, :key => key}), 3)
88
190
  end
89
191
 
192
+ # Remove a public key from user account.
193
+ #
194
+ # Requires authenticated client.
195
+ #
196
+ # @param id [String] Id of the public key to remove.
197
+ # @return [Boolean] True if removal was successful, false otherwise.
198
+ # @see Octokit::Client
199
+ # @see http://developer.github.com/v3/users/keys/#delete-a-public-key
200
+ # @example
201
+ # @client.remove_key(1)
90
202
  def remove_key(id, options={})
91
- delete("user/keys/#{id}", options, 3, true, raw=true)
203
+ delete("user/keys/#{id}", options, 3, true, raw=true).status == 204
92
204
  end
93
205
 
206
+ # List email addresses for a user.
207
+ #
208
+ # Requires authenticated client.
209
+ #
210
+ # @return [Array<String>] Array of email addresses.
211
+ # @see Octokit::Client
212
+ # @see http://developer.github.com/v3/users/emails/#list-email-addresses-for-a-user
213
+ # @example
214
+ # @client.emails
94
215
  def emails(options={})
95
216
  get("user/emails", options, 3)
96
217
  end
97
218
 
219
+ # Add email address to user.
220
+ #
221
+ # Requires authenticated client.
222
+ #
223
+ # @param email [String] Email address to add to the user.
224
+ # @return [Array<String>] Array of all email addresses of the user.
225
+ # @see Octokit::Client
226
+ # @see http://developer.github.com/v3/users/emails/#add-email-addresses
227
+ # @example
228
+ # @client.add_email('new_email@user.com')
98
229
  def add_email(email, options={})
99
230
  post("user/emails", options.merge({:email => email}), 3)
100
231
  end
101
232
 
233
+ # Remove email from user.
234
+ #
235
+ # Requires authenticated client.
236
+ #
237
+ # @param email [String] Email address to remove.
238
+ # @return [Array<String>] Array of all email addresses of the user.
239
+ # @see Octokit::Client
240
+ # @see http://developer.github.com/v3/users/emails/#delete-email-addresses
241
+ # @example
242
+ # @client.remove_email('old_email@user.com')
102
243
  def remove_email(email, options={})
103
244
  delete("user/emails", options.merge({:email => email}), 3, true, raw=true).status == 204
104
245
  end