Update documentation to include epic todos

doc/api/epics.md

@@ -210,3 +210,71 @@ DELETE /groups/:id/epics/:epic_iid
 ```bash
 curl --header DELETE "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/1/epics/5?title=New%20Title
 ```
+
+## Create a todo
+
+Manually creates a todo for the current user on an epic. If
+there already exists a todo for the user on that epic, status code `304` is
+returned.
+
+```
+POST /groups/:id/epics/:epic_iid/todo
+```
+
+| Attribute   | Type    | Required | Description                          |
+|-------------|---------|----------|--------------------------------------|
+| `id`        | integer/string | yes   | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user  |
+| `epic_iid ` | integer | yes          | The internal ID of a group's epic |
+
+```bash
+curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/1/epics/5/todo
+```
+
+Example response:
+
+```json
+{
+  "id": 112,
+  "group": {
+    "id": 1,
+    "name": "Gitlab",
+    "path": "gitlab",
+    "kind": "group",
+    "full_path": "base/gitlab",
+    "parent_id": null
+  },
+  "author": {
+    "name": "Administrator",
+    "username": "root",
+    "id": 1,
+    "state": "active",
+    "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
+    "web_url": "https://gitlab.example.com/root"
+  },
+  "action_name": "marked",
+  "target_type": "epic",
+  "target": {
+    "id": 30,
+    "iid": 5,
+    "group_id": 1,
+    "title": "Ea cupiditate dolores ut vero consequatur quasi veniam voluptatem et non.",
+    "description": "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.",
+    "author":{
+      "id": 7,
+      "name": "Pamella Huel",
+      "username": "arnita",
+      "state": "active",
+      "avatar_url": "http://www.gravatar.com/avatar/a2f5c6fcef64c9c69cb8779cb292be1b?s=80&d=identicon",
+      "web_url": "http://localhost:3001/arnita"
+    },
+    "start_date": null,
+    "end_date": null,
+    "created_at": "2018-01-21T06:21:13.165Z",
+    "updated_at": "2018-01-22T12:41:41.166Z"
+  },
+  "target_url": "https://gitlab.example.com/groups/epics/5",
+  "body": "Vel voluptas atque dicta mollitia adipisci qui at.",
+  "state": "pending",
+  "created_at": "2016-07-01T11:09:13.992Z"
+}
+```

doc/workflow/todos.md

@@ -26,8 +26,8 @@ will still be shown in the body of the _To do_ tab.
 A Todo appears in your Todos dashboard when:
 
 - an issue or merge request is assigned to you,
-- you are `@mentioned` in an issue or merge request, be it the description of
-  the issue/merge request or in a comment,
+- you are `@mentioned` in an issue, merge request or epic, be it the description of
+  the issue/merge request/epic or in a comment,
 - you are `@mentioned` in a comment on a commit,
 - a job in the CI pipeline running for your merge request failed, but this
   job is not allowed to fail.
@@ -60,14 +60,14 @@ for filtering; otherwise, they appear as normal.
 
 ### Manually creating a Todo
 
-You can also add an issue or merge request to your Todos dashboard by clicking
-the "Add todo" button in the issue or merge request sidebar.
+You can also add an issue, merge request or epic to your Todos dashboard by clicking
+the "Add todo" button in the issue, merge request or epic sidebar.
 
 ![Adding a Todo from the issuable sidebar](img/todos_add_todo_sidebar.png)
 
 ## Marking a Todo as done
 
-Any action to the corresponding issue or merge request will mark your Todo as
+Any action to the corresponding issue, merge request or epic will mark your Todo as
 **Done**. Actions that dismiss Todos include:
 
 - changing the assignee
@@ -81,10 +81,10 @@ Todos are personal, and they're only marked as done if the action is coming from
 you. If you close the issue or merge request, your Todo will automatically
 be marked as done.
 
-If someone else closes, merges, or takes action on the issue or merge
+If someone else closes, merges, or takes action on the issue, epic or merge
 request, your Todo will remain pending. This prevents other users from closing issues without you being notified.
 
-There is just one Todo per issue or merge request, so mentioning a user a
+There is just one Todo per issue, epic or merge request, so mentioning a user a
 hundred times in an issue will only trigger one Todo.
 
 ---
@@ -94,7 +94,7 @@ corresponding **Done** button, and it will disappear from your Todo list.
 
 ![A Todo in the Todos dashboard](img/todo_list_item.png)
 
-A Todo can also be marked as done from the issue or merge request sidebar using
+A Todo can also be marked as done from the issue, merge request or epic sidebar using
 the "Mark todo as done" button.
 
 ![Mark todo as done from the issuable sidebar](img/todos_mark_done_sidebar.png)
@@ -109,8 +109,9 @@ There are four kinds of filters you can use on your Todos dashboard.
 | Filter  | Description |
 | ------- | ----------- |
 | Project | Filter by project |
+| Group   | Filter by group |
 | Author  | Filter by the author that triggered the Todo |
-| Type    | Filter by issue or merge request |
+| Type    | Filter by issue, merge request or epic |
 | Action  | Filter by the action that triggered the Todo |
 
 You can also filter by more than one of these at the same time. The possible Actions are `Any Action`, `Assigned`, `Mentioned`, `Added`, `Pipelines`, and `Directly Addressed`, [as described above](#what-triggers-a-todo).