Complete API for repo-issues

Add missing methods to set the following fields of 'IssueRepoOptions':
- specific milestone
- specific assignee
- creator
- mentioned

Author: andreasabel

github.cabal

@@ -1,7 +1,6 @@
 cabal-version:      >=1.10
 name:               github
-version:            0.27
-x-revision:         1
+version:            0.28
 synopsis:           Access to the GitHub API, v3.
 category:           Network
 description:

src/GitHub/Data/Options.hs

@@ -38,12 +38,16 @@ module GitHub.Data.Options (
     -- * Repo issues
     IssueRepoMod,
     issueRepoModToQueryString,
+    optionsCreator,
+    optionsMentioned,
     optionsIrrelevantMilestone,
     optionsAnyMilestone,
     optionsNoMilestone,
+    optionsMilestone,
     optionsIrrelevantAssignee,
     optionsAnyAssignee,
     optionsNoAssignee,
+    optionsAssignee,
     -- * Data
     IssueState (..),
     MergeableState (..),
@@ -351,7 +355,7 @@ sortByLongRunning = PRMod $ \opts ->
 -- Issues
 -------------------------------------------------------------------------------
 
--- | See <https://developer.github.com/v3/issues/#parameters>.
+-- | See <https://docs.github.com/en/rest/reference/issues#list-issues-assigned-to-the-authenticated-user--parameters>.
 data IssueOptions = IssueOptions
     { issueOptionsFilter    :: !IssueFilter
     , issueOptionsState     :: !(Maybe IssueState)
@@ -373,7 +377,7 @@ defaultIssueOptions = IssueOptions
     , issueOptionsSince     = Nothing
     }
 
--- | See <https://developer.github.com/v3/issues/#parameters>.
+-- | See <https://docs.github.com/en/rest/reference/issues#list-issues-assigned-to-the-authenticated-user--parameters>.
 newtype IssueMod = IssueMod (IssueOptions -> IssueOptions)
 
 instance Semigroup IssueMod where
@@ -491,16 +495,70 @@ issueFilter f = IssueMod $ \opts ->
 -- Issues repo
 -------------------------------------------------------------------------------
 
+-- | See <https://docs.github.com/en/rest/reference/issues#list-repository-issues>.
+--   Retrieved: 2021-12-08
+--
+-- Parameters of "list repository issues" (@get /repos/{owner}/{repo}/issues@)
+--
+-- * milestone : string
+--
+--   If an integer is passed, it should refer to a milestone by its number field. If the string * is passed, issues with any milestone are accepted. If the string none is passed, issues without milestones are returned.
+--
+-- * state : string
+--
+--   Indicates the state of the issues to return. Can be either open, closed, or all.
+--   Default: open
+--
+-- * assignee : string
+--
+--   Can be the name of a user. Pass in none for issues with no assigned user, and * for issues assigned to any user.
+--
+-- * creator : string
+--
+--   The user that created the issue.
+--
+-- * mentioned : string
+--
+--   A user that's mentioned in the issue.
+--
+-- * labels : string
+--
+--   A list of comma separated label names. Example: bug,ui,@high
+--
+-- * sort : string
+--
+--   What to sort results by. Can be either created, updated, comments.
+--   Default: created
+--
+-- * direction : string
+--
+--   One of asc (ascending) or desc (descending).
+--   Default: desc
+--
+-- * since : string
+--
+--   Only show notifications updated after the given time. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.
+--
+-- * per_page : integer
+--
+--   Results per page (max 100)
+--   Default: 30
+--
+-- * page : integer
+--
+--   Page number of the results to fetch.
+--   Default: 1
+--
 data IssueRepoOptions = IssueRepoOptions
-    { issueRepoOptionsMilestone :: !(FilterBy (Id Milestone))
-    , issueRepoOptionsState     :: !(Maybe IssueState)
-    , issueRepoOptionsAssignee  :: !(FilterBy (Name User))
-    , issueRepoOptionsCreator   :: !(Maybe (Name User))
-    , issueRepoOptionsMentioned :: !(Maybe (Name User))
-    , issueRepoOptionsLabels    :: ![Name IssueLabel]
-    , issueRepoOptionsSort      :: !SortIssue
-    , issueRepoOptionsDirection :: !SortDirection
-    , issueRepoOptionsSince     :: !(Maybe UTCTime)
+    { issueRepoOptionsMilestone :: !(FilterBy (Id Milestone))   -- ^ 'optionsMilestone' etc.
+    , issueRepoOptionsState     :: !(Maybe IssueState)          -- ^ 'HasState'
+    , issueRepoOptionsAssignee  :: !(FilterBy (Name User))      -- ^ 'optionsAssignee' etc.
+    , issueRepoOptionsCreator   :: !(Maybe (Name User))         -- ^ 'optionsCreator'
+    , issueRepoOptionsMentioned :: !(Maybe (Name User))         -- ^ 'optionsMentioned'
+    , issueRepoOptionsLabels    :: ![Name IssueLabel]           -- ^ 'HasLabels'
+    , issueRepoOptionsSort      :: !SortIssue                   -- ^ 'HasCreatedUpdated' and 'HasComments'
+    , issueRepoOptionsDirection :: !SortDirection               -- ^ 'HasDirection'
+    , issueRepoOptionsSince     :: !(Maybe UTCTime)             -- ^ 'HasSince'
     }
   deriving
     (Eq, Ord, Show, Generic, Typeable, Data)
@@ -579,7 +637,17 @@ issueRepoOptionsToQueryString IssueRepoOptions {..} =
 -- Issues repo modifiers
 -------------------------------------------------------------------------------
 
--- | Don't care about milestones.
+-- | Issues created by a certain user.
+optionsCreator :: Name User -> IssueRepoMod
+optionsCreator u = IssueRepoMod $ \opts ->
+    opts { issueRepoOptionsCreator = Just u }
+
+-- | Issue mentioning the given user.
+optionsMentioned :: Name User -> IssueRepoMod
+optionsMentioned u = IssueRepoMod $ \opts ->
+    opts { issueRepoOptionsMentioned = Just u }
+
+-- | Don't care about milestones (default).
 --
 -- 'optionsAnyMilestone' means there should be some milestone, but it can be any.
 --
@@ -588,22 +656,37 @@ optionsIrrelevantMilestone :: IssueRepoMod
 optionsIrrelevantMilestone = IssueRepoMod $ \opts ->
     opts { issueRepoOptionsMilestone = FilterNotSpecified }
 
+-- | Issues that have a milestone.
 optionsAnyMilestone :: IssueRepoMod
 optionsAnyMilestone = IssueRepoMod $ \opts ->
     opts { issueRepoOptionsMilestone = FilterAny }
 
+-- | Issues that have no milestone.
 optionsNoMilestone :: IssueRepoMod
 optionsNoMilestone = IssueRepoMod $ \opts ->
     opts { issueRepoOptionsMilestone = FilterNone }
 
+-- | Issues with the given milestone.
+optionsMilestone :: Id Milestone -> IssueRepoMod
+optionsMilestone m = IssueRepoMod $ \opts ->
+    opts { issueRepoOptionsMilestone = FilterBy m }
+
+-- | Issues with or without assignee (default).
 optionsIrrelevantAssignee :: IssueRepoMod
 optionsIrrelevantAssignee = IssueRepoMod $ \opts ->
     opts { issueRepoOptionsAssignee = FilterNotSpecified }
 
+-- | Issues assigned to someone.
 optionsAnyAssignee :: IssueRepoMod
 optionsAnyAssignee = IssueRepoMod $ \opts ->
     opts { issueRepoOptionsAssignee = FilterAny }
 
+-- | Issues assigned to nobody.
 optionsNoAssignee :: IssueRepoMod
 optionsNoAssignee = IssueRepoMod $ \opts ->
     opts { issueRepoOptionsAssignee = FilterNone }
+
+-- | Issues assigned to a specific user.
+optionsAssignee :: Name User -> IssueRepoMod
+optionsAssignee u = IssueRepoMod $ \opts ->
+    opts { issueRepoOptionsAssignee = FilterBy u }