Add documentation for status endpoints

haskell-github · Oct 8, 2017 · d7d8572 · d7d8572
1 parent e631f83
commit d7d8572
Show file tree

Hide file tree

Showing 2 changed files with 30 additions and 0 deletions.
diff --git a/src/GitHub.hs b/src/GitHub.hs
@@ -328,6 +328,12 @@ module GitHub (
     usersFollowingR,
     usersFollowedByR,
 
+    -- ** Statuses
+    -- | See <https://developer.github.com/v3/repos/statuses/>
+    createStatusR,
+    statusesForR,
+    statusForR,
+
     -- * Data definitions
     module GitHub.Data,
     -- * Request handling
@@ -361,6 +367,7 @@ import GitHub.Endpoints.Repos.Comments
 import GitHub.Endpoints.Repos.Commits
 import GitHub.Endpoints.Repos.Forks
 import GitHub.Endpoints.Repos.Releases
+import GitHub.Endpoints.Repos.Statuses
 import GitHub.Endpoints.Repos.Webhooks
 import GitHub.Endpoints.Search
 import GitHub.Endpoints.Users

diff --git a/src/GitHub/Endpoints/Repos/Statuses.hs b/src/GitHub/Endpoints/Repos/Statuses.hs
@@ -1,3 +1,7 @@
+-----------------------------------------------------------------------------
+-- |
+-- License     :  BSD-3-Clause
+-- Maintainer  :  Oleg Grenrus <oleg.grenrus@iki.fi>
 --
 -- The repo statuses API as described on
 -- <https://developer.github.com/v3/repos/statuses/>.
@@ -16,28 +20,47 @@ import GitHub.Internal.Prelude
 import GitHub.Request
 import Prelude ()
 
+-- | Create a new status
+--
+-- > createStatus (BasicAuth user password) "thoughtbot" "paperclip"
+-- >   "41f685f6e01396936bb8cd98e7cca517e2c7d96b"
+-- >   (NewStatus StatusSuccess Nothing "Looks good!" Nothing)
 createStatus :: Auth -> Name Owner -> Name Repo -> Name Commit -> NewStatus -> IO (Either Error Status)
 createStatus auth owner repo sha ns =
     executeRequest auth $ createStatusR owner repo sha ns
 
+-- | Create a new status
+-- See <https://developer.github.com/v3/repos/statuses/#create-a-status>
 createStatusR :: Name Owner -> Name Repo -> Name Commit -> NewStatus -> Request 'RW Status
 createStatusR owner repo sha =
     command Post parts . encode
     where
         parts = ["repos", toPathPart owner, toPathPart repo, "statuses", toPathPart sha]
 
+-- | All statuses for a commit
+--
+-- > statusesFor (BasicAuth user password) "thoughtbot" "paperclip"
+-- >   "41f685f6e01396936bb8cd98e7cca517e2c7d96b"
 statusesFor :: Auth -> Name Owner -> Name Repo -> Name Commit -> IO (Either Error (Vector Status))
 statusesFor auth user repo sha =
     executeRequest auth $ statusesForR user repo sha FetchAll
 
+-- | All statuses for a commit
+-- See <https://developer.github.com/v3/repos/statuses/#list-statuses-for-a-specific-ref>
 statusesForR :: Name Owner -> Name Repo -> Name Commit -> FetchCount -> Request 'RW (Vector Status)
 statusesForR user repo sha =
     pagedQuery ["repos", toPathPart user, toPathPart repo, "commits", toPathPart sha, "statuses"] []
 
+-- | The combined status for a specific commit
+--
+-- > statusFor (BasicAuth user password) "thoughtbot" "paperclip"
+-- >   "41f685f6e01396936bb8cd98e7cca517e2c7d96b"
 statusFor :: Auth -> Name Owner -> Name Repo -> Name Commit -> IO (Either Error CombinedStatus)
 statusFor auth user repo sha =
     executeRequest auth $ statusForR user repo sha
 
+-- | The combined status for a specific commit
+-- See <https://developer.github.com/v3/repos/statuses/#get-the-combined-status-for-a-specific-ref>
 statusForR :: Name Owner -> Name Repo -> Name Commit -> Request 'RW CombinedStatus
 statusForR user repo sha =
     query ["repos", toPathPart user, toPathPart repo, "commits", toPathPart sha, "status"] []