[pkg-perl-tools] 05/07: Add documentation for exported subs

Wed Nov 2 01:18:56 UTC 2016

This is an automated email from the git hooks/post-receive script.

alexm-guest pushed a commit to branch master
in repository pkg-perl-tools.

commit 880efb342a154973818b230c63bcdfcb99296a8f
Author: Alex Muntada <alexm at alexm.org>
Date:   Wed Nov 2 01:52:17 2016 +0100

    Add documentation for exported subs
---
 lib/Debian/PkgPerl/GitHub.pm | 158 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 158 insertions(+)

diff --git a/lib/Debian/PkgPerl/GitHub.pm b/lib/Debian/PkgPerl/GitHub.pm
index 983b119..a2396df 100644
--- a/lib/Debian/PkgPerl/GitHub.pm
+++ b/lib/Debian/PkgPerl/GitHub.pm
@@ -3,6 +3,19 @@ package Debian::PkgPerl::GitHub;
 use strict;
 use warnings;
 
+
+=head1 NAME
+
+Debian::PkgPerl::GitHub - Help forwarding a bug or a patch to GitHub
+
+=head1 DESCRIPTION
+
+This module exports several helpers that that provide support for
+forwarding patches to GitHub as pull requests.
+
+=cut
+
+
 use File::Temp qw(tempdir);
 use Git::Repository;
 
@@ -14,12 +27,72 @@ our @EXPORT = qw(
     create_pull_request
 );
 
+=head2 fork_exists($gh, $user, $repo)
+
+Checks if a GitHub user has already forked a repository.
+
+=head3 Parameters:
+
+=over
+
+=item * $gh
+
+Net::GitHub object that must be already authenticated.
+
+=item * $user
+
+GitHub username.
+
+=item * $repo
+
+GitHub repository name.
+
+=back
+
+=head3 Returns:
+
+Boolean value.
+
+=cut
+
 sub fork_exists {
     my ($gh, $user, $repo) = @_;
 
     return !!$gh->repos->set_default_user_repo($user, $repo);
 }
 
+=head2 create_fork($gh, $owner, $repo, $orgname)
+
+Creates a repository fork by an organization.
+
+=head3 Parameters:
+
+=over
+
+=item * $gh
+
+Net::GitHub object that must be already authenticated.
+
+=item * $owner
+
+Repository owner.
+
+=item * $repo
+
+Repository being forked.
+
+=item * $orgname
+
+Organization that is forking the repository.
+
+=back
+
+=head3 Returns:
+
+The new forked repository.
+
+=cut
+
 sub create_fork {
     my ($gh, $owner, $repo, $orgname) = @_;
 
@@ -27,6 +100,44 @@ sub create_fork {
     return $gh->repos->create_fork($orgname);
 }
 
+=head2 clone_branch_patch_push($user, $repo, $branch, $patch, $comment)
+
+Clones a repository in a temporary directory, creates a new branch,
+applies the patch, commits the change, pushes it and removes the
+temporary working copy.
+
+=head3 Parameters:
+
+=over
+
+=item * $user
+
+User cloning the repository.
+
+=item * $repo
+
+Repository being cloned.
+
+=item * $branch
+
+Name of the branch being created.
+
+=item * $patch
+
+Full pathname to the file containing the patch.
+
+=item * $comment
+
+Message used in the commit.
+
+=back
+
+=head3 Returns:
+
+Nothing.
+
+=cut
+
 sub clone_branch_patch_push {
     my ($user, $repo, $branch, $patch, $comment) = @_;
 
@@ -54,6 +165,37 @@ sub clone_branch_patch_push {
     $r->run( push => 'origin', $branch, { quiet => 1 } );
 }
 
+=head2 create_pull_request($gh, $user, $repo, $params)
+
+=head3 Parameters:
+
+=over
+
+=item * $gh
+
+Net::GitHub object that must be already authenticated.
+
+=item * $user
+
+User performing the pull request.
+
+=item * $repo
+
+Repository receiving the pull request.
+
+=item * $params
+
+Hash reference with pull request parameters (usually B<title>, B<body>,
+B<head> and B<base>.) See L<Net::GitHub::V3::PullRequests> for details.
+
+=back
+
+=head3 Returns:
+
+Pull request URL on success, nothing otherwise.
+
+=cut
+
 sub create_pull_request {
     my ($gh, $user, $repo, $params) = @_;
 
@@ -61,3 +203,19 @@ sub create_pull_request {
     my $pull = $gh->pull_request->create_pull($params);
     return $pull->{html_url} if $pull;
 }
+
+=head1 LICENSE AND COPYRIGHT
+
+=over
+
+=item Copyright 2016 Alex Muntada.
+
+=back
+
+This program is free software; you can redistribute it and/or modify it
+under the terms of either: the GNU General Public License as published
+by the Free Software Foundation; or the Artistic License.
+
+See http://dev.perl.org/licenses/ for more information.
+
+=cut

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/pkg-perl-tools.git

