Merge pull request KnpLabs#290 from lucasmichot/feature/gitdata

Add docblocks for git data
flyeven · Jul 7, 2015 · 99c6b87 · 99c6b87
2 parents 934ad37 + b5d61c3
commit 99c6b87
Show file tree

Hide file tree

Showing 5 changed files with 166 additions and 0 deletions.
diff --git a/lib/Github/Api/GitData/Blobs.php b/lib/Github/Api/GitData/Blobs.php
@@ -11,6 +11,11 @@
  */
 class Blobs extends AbstractApi
 {
+    /**
+     * Configure the Acccept header depending on the blob type.
+     *
+     * @param string|null $bodyType
+     */
     public function configure($bodyType = null)
     {
         if ('raw' == $bodyType) {
@@ -20,13 +25,33 @@ public function configure($bodyType = null)
         }
     }
 
+    /**
+     * Show a blob of a sha for a repository.
+     *
+     * @param string $username
+     * @param string $repository
+     * @param string $sha
+     *
+     * @return array
+     */
     public function show($username, $repository, $sha)
     {
         $response = $this->get('repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/git/blobs/'.rawurlencode($sha));
 
         return $response;
     }
 
+    /**
+     * Create a blob of a sha for a repository.
+     *
+     * @param string $username
+     * @param string $repository
+     * @param array  $params
+     *
+     * @return array
+     *
+     * @throws \Github\Exception\MissingArgumentException
+     */
     public function create($username, $repository, array $params)
     {
         if (!isset($params['content'], $params['encoding'])) {

diff --git a/lib/Github/Api/GitData/Commits.php b/lib/Github/Api/GitData/Commits.php
@@ -11,11 +11,31 @@
  */
 class Commits extends AbstractApi
 {
+    /**
+     * Show a commit for a repository.
+     *
+     * @param string $username
+     * @param string $repository
+     * @param string $sha
+     *
+     * @return array
+     */
     public function show($username, $repository, $sha)
     {
         return $this->get('repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/git/commits/'.rawurlencode($sha));
     }
 
+    /**
+     * Create a commit for a repository.
+     *
+     * @param string $username
+     * @param string $repository
+     * @param array  $params
+     *
+     * @return array
+     *
+     * @throws \Github\Exception\MissingArgumentException
+     */
     public function create($username, $repository, array $params)
     {
         if (!isset($params['message'], $params['tree'], $params['parents'])) {

diff --git a/lib/Github/Api/GitData/References.php b/lib/Github/Api/GitData/References.php
@@ -11,28 +11,72 @@
  */
 class References extends AbstractApi
 {
+    /**
+     * Get all references of a repository.
+     *
+     * @param string $username
+     * @param string $repository
+     *
+     * @return array
+     */
     public function all($username, $repository)
     {
         return $this->get('repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/git/refs');
     }
 
+    /**
+     * Get all branches of a repository.
+     *
+     * @param string $username
+     * @param string $repository
+     *
+     * @return array
+     */
     public function branches($username, $repository)
     {
         return $this->get('repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/git/refs/heads');
     }
 
+    /**
+     * Get all tags of a repository.
+     *
+     * @param string $username
+     * @param string $repository
+     *
+     * @return array
+     */
     public function tags($username, $repository)
     {
         return $this->get('repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/git/refs/tags');
     }
 
+    /**
+     * Show the reference of a repository.
+     *
+     * @param string $username
+     * @param string $repository
+     * @param string $reference
+     *
+     * @return array
+     */
     public function show($username, $repository, $reference)
     {
         $reference = $this->encodeReference($reference);
 
         return $this->get('repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/git/refs/'.$reference);
     }
 
+    /**
+     * Create a reference for a repository.
+     *
+     * @param string $username
+     * @param string $repository
+     * @param array  $params
+     *
+     * @return array
+     *
+     * @throws \Github\Exception\MissingArgumentException
+     */
     public function create($username, $repository, array $params)
     {
         if (!isset($params['ref'], $params['sha'])) {
@@ -42,6 +86,18 @@ public function create($username, $repository, array $params)
         return $this->post('repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/git/refs', $params);
     }
 
+    /**
+     * Update a reference for a repository.
+     *
+     * @param string $username
+     * @param string $repository
+     * @param string $reference
+     * @param array  $params
+     *
+     * @return array
+     *
+     * @throws \Github\Exception\MissingArgumentException
+     */
     public function update($username, $repository, $reference, array $params)
     {
         if (!isset($params['sha'])) {
@@ -53,13 +109,29 @@ public function update($username, $repository, $reference, array $params)
         return $this->patch('repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/git/refs/'.$reference, $params);
     }
 
+    /**
+     * Delete a reference of a repository.
+     *
+     * @param string $username
+     * @param string $repository
+     * @param string $reference
+     *
+     * @return array
+     */
     public function remove($username, $repository, $reference)
     {
         $reference = $this->encodeReference($reference);
 
         return $this->delete('repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/git/refs/'.$reference);
     }
 
+    /**
+     * Encode the raw reference.
+     *
+     * @param string $rawReference
+     *
+     * @return string
+     */
     private function encodeReference($rawReference)
     {
         return implode('/', array_map('rawurlencode', explode('/', $rawReference)));

diff --git a/lib/Github/Api/GitData/Tags.php b/lib/Github/Api/GitData/Tags.php
@@ -11,16 +11,44 @@
  */
 class Tags extends AbstractApi
 {
+    /**
+     * Get all tags for a repository.
+     *
+     * @param string $username
+     * @param string $repository
+     *
+     * @return array
+     */
     public function all($username, $repository)
     {
         return $this->get('repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/git/refs/tags');
     }
 
+    /**
+     * Get a tag for a repository.
+     *
+     * @param string $username
+     * @param string $repository
+     * @param string $sha
+     *
+     * @return array
+     */
     public function show($username, $repository, $sha)
     {
         return $this->get('repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/git/tags/'.rawurlencode($sha));
     }
 
+    /**
+     * Create a tag for a repository.
+     *
+     * @param string $username
+     * @param string $repository
+     * @param array  $params
+     *
+     * @return array
+     *
+     * @throws \Github\Exception\MissingArgumentException
+     */
     public function create($username, $repository, array $params)
     {
         if (!isset($params['tag'], $params['message'], $params['object'], $params['type'])) {

diff --git a/lib/Github/Api/GitData/Trees.php b/lib/Github/Api/GitData/Trees.php
@@ -11,11 +11,32 @@
  */
 class Trees extends AbstractApi
 {
+    /**
+     * Get the tree for a repository.
+     *
+     * @param string $username
+     * @param string $repository
+     * @param string $sha
+     * @param bool   $recursive
+     *
+     * @return array
+     */
     public function show($username, $repository, $sha, $recursive = false)
     {
         return $this->get('repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/git/trees/'.rawurlencode($sha), array('recursive' => $recursive ? 1 : null));
     }
 
+    /**
+     * Create tree for a repository.
+     *
+     * @param string $username
+     * @param string $repository
+     * @param array  $params
+     *
+     * @return array
+     *
+     * @throws \Github\Exception\MissingArgumentException
+     */
     public function create($username, $repository, array $params)
     {
         if (!isset($params['tree']) || !is_array($params['tree'])) {