Merge branch 'doc-API-line-range-is-optional' into 'master'

MR Discussions API: document parameters "line_code" & "line_type"

See merge request gitlab-org/gitlab!51525

doc/api/discussions.md

@@ -852,33 +852,42 @@ Parameters for all comments:
 | `position[base_sha]`                     | string         | yes      | Base commit SHA in the source branch |
 | `position[start_sha]`                    | string         | yes      | SHA referencing commit in target branch |
 | `position[head_sha]`                     | string         | yes      | SHA referencing HEAD of this merge request |
-| `position[position_type]`                | string         | yes      | Type of the position reference', allowed values: 'text' or 'image' |
+| `position[position_type]`                | string         | yes      | Type of the position reference', allowed values: `text` or `image` |
 | `position[new_path]`                     | string         | no       | File path after change |
-| `position[new_line]`                     | integer        | no       | Line number after change (for 'text' diff notes) |
+| `position[new_line]`                     | integer        | no       | Line number after change (for `text` diff notes) |
 | `position[old_path]`                     | string         | no       | File path before change |
-| `position[old_line]`                     | integer        | no       | Line number before change (for 'text' diff notes) |
+| `position[old_line]`                     | integer        | no       | Line number before change (for `text` diff notes) |
 | `position[line_range]`                   | hash           | no       | Line range for a multi-line diff note |
-| `position[width]`                        | integer        | no       | Width of the image (for 'image' diff notes) |
-| `position[height]`                       | integer        | no       | Height of the image (for 'image' diff notes) |
-| `position[x]`                            | integer        | no       | X coordinate (for 'image' diff notes) |
-| `position[y]`                            | integer        | no       | Y coordinate (for 'image' diff notes) |
+| `position[width]`                        | integer        | no       | Width of the image (for `image` diff notes) |
+| `position[height]`                       | integer        | no       | Height of the image (for `image` diff notes) |
+| `position[x]`                            | integer        | no       | X coordinate (for `image` diff notes) |
+| `position[y]`                            | integer        | no       | Y coordinate (for `image` diff notes) |
+
+```shell
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions?body=comment"
+```
 
 Parameters for multiline comments only:
 
 | Attribute                                | Type           | Required | Description |
 | ---------------------------------------- | -------------- | -------- | ----------- |
 | `position[line_range][start]`            | hash           | no       | Multiline note starting line |
-| `position[line_range][start][line_code]` | string         | no       | Line code for the start line |
-| `position[line_range][start][type]`      | string         | no       | Line type for the start line |
+| `position[line_range][start][line_code]` | string         | yes      | [Line code](#line-code) for the start line |
+| `position[line_range][start][type]`      | string         | yes      | Use `new` for lines added by this commit, otherwise `old`. |
 | `position[line_range][end]`              | hash           | no       | Multiline note ending line |
-| `position[line_range][end][line_code]`   | string         | no       | Line code for the end line |
-| `position[line_range][end][type]`        | string         | no      | Line type for the end line |
+| `position[line_range][end][line_code]`   | string         | yes      | [Line code](#line-code) for the end line |
+| `position[line_range][end][type]`        | string         | yes      | Use `new` for lines added by this commit, otherwise `old`. |
 
-```shell
-curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions?body=comment"
-```
+#### Line code
+
+A line code is of the form `<SHA>_<old>_<new>`:
+
+- `<SHA>` is the SHA1 hash of the filename.
+- `<old>` is the line number before the change.
+- `<new>` is the line number after the change.
 
-There is currently no functional documented method of starting merge request discussions. Read [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/228807) for reflections.
+For example, when commenting on an added line number 5, the line code
+looks like `adc83b19e793491b1c6ea0fd8b46cd9f32e292fc_5_5`.
 
 ### Resolve a merge request thread
 
@@ -1159,15 +1168,15 @@ Parameters:
 | `position[base_sha]`      | string         | yes      | Base commit SHA in the source branch |
 | `position[start_sha]`     | string         | yes      | SHA referencing commit in target branch |
 | `position[head_sha]`      | string         | yes      | SHA referencing HEAD of this commit |
-| `position[position_type]` | string         | yes      | Type of the position reference', allowed values: 'text' or 'image' |
+| `position[position_type]` | string         | yes      | Type of the position reference', allowed values: `text` or `image` |
 | `position[new_path]`      | string         | no       | File path after change |
 | `position[new_line]`      | integer        | no       | Line number after change |
 | `position[old_path]`      | string         | no       | File path before change |
 | `position[old_line]`      | integer        | no       | Line number before change |
-| `position[width]`         | integer        | no       | Width of the image (for 'image' diff notes) |
-| `position[height]`        | integer        | no       | Height of the image (for 'image' diff notes) |
-| `position[x]`             | integer        | no       | X coordinate (for 'image' diff notes) |
-| `position[y]`             | integer        | no       | Y coordinate (for 'image' diff notes) |
+| `position[width]`         | integer        | no       | Width of the image (for `image` diff notes) |
+| `position[height]`        | integer        | no       | Height of the image (for `image` diff notes) |
+| `position[x]`             | integer        | no       | X coordinate (for `image` diff notes) |
+| `position[y]`             | integer        | no       | Y coordinate (for `image` diff notes) |
 
 ```shell
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions?body=comment"

doc/api/issue_links.md

@@ -166,7 +166,7 @@ DELETE /projects/:id/issues/:issue_iid/links/:issue_link_id
 | `id`        | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user  |
 | `issue_iid` | integer | yes      | The internal ID of a project's issue |
 | `issue_link_id` | integer/string | yes      | The ID of an issue relationship |
-| `link_type` | string  | no | The type of the relation ('relates_to', 'blocks', 'is_blocked_by'), defaults to 'relates_to' |
+| `link_type` | string  | no | The type of the relation (`relates_to`, `blocks`, `is_blocked_by`), defaults to `relates_to` |
 
 ```json
 {

doc/api/pipeline_schedules.md

@@ -115,7 +115,7 @@ POST /projects/:id/pipeline_schedules
 | `description`   | string         | yes      | The description of the pipeline schedule.                                                                               |
 | `ref`           | string         | yes      | The branch or tag name that is triggered.                                                                               |
 | `cron`          | string         | yes      | The [cron](https://en.wikipedia.org/wiki/Cron) schedule, for example: `0 1 * * *`.                                      |
-| `cron_timezone` | string         | no       | The timezone supported by `ActiveSupport::TimeZone`, for example: `Pacific Time (US & Canada)` (default: `'UTC'`).      |
+| `cron_timezone` | string         | no       | The timezone supported by `ActiveSupport::TimeZone`, for example: `Pacific Time (US & Canada)` (default: `UTC`).        |
 | `active`        | boolean        | no       | The activation of pipeline schedule. If false is set, the pipeline schedule is initially deactivated (default: `true`). |
 
 ```shell

doc/api/project_snippets.md

@@ -140,7 +140,7 @@ Parameters:
 | `description`         | string          | no       | Description of a snippet                                                                                        |
 | `visibility`          | string          | no       | Snippet's [visibility](#snippet-visibility-level)                                                               |
 | `files`               | array of hashes | no       | An array of snippet files                                                                                       |
-| `files:action`        | string          | yes      | Type of action to perform on the file, one of: 'create', 'update', 'delete', 'move'                             |
+| `files:action`        | string          | yes      | Type of action to perform on the file, one of: `create`, `update`, `delete`, `move`                             |
 | `files:file_path`     | string          | no       | File path of the snippet file                                                                                   |
 | `files:previous_path` | string          | no       | Previous path of the snippet file                                                                               |
 | `files:content`       | string          | no       | Content of the snippet file                                                                                     |

doc/api/repository_files.md

@@ -203,7 +203,7 @@ Parameters:
 - `file_path` (required) - URL encoded full path to new file. Ex. lib%2Fclass%2Erb
 - `branch` (required) - Name of the branch
 - `start_branch` (optional) - Name of the branch to start the new commit from
-- `encoding` (optional) - Change encoding to 'base64'. Default is text.
+- `encoding` (optional) - Change encoding to `base64`. Default is `text`.
 - `author_email` (optional) - Specify the commit author's email address
 - `author_name` (optional) - Specify the commit author's name
 - `content` (required) - File content
@@ -238,7 +238,7 @@ Parameters:
 - `file_path` (required) - URL encoded full path to new file. Ex. lib%2Fclass%2Erb
 - `branch` (required) - Name of the branch
 - `start_branch` (optional) - Name of the branch to start the new commit from
-- `encoding` (optional) - Change encoding to 'base64'. Default is text.
+- `encoding` (optional) - Change encoding to `base64`. Default is `text`.
 - `author_email` (optional) - Specify the commit author's email address
 - `author_name` (optional) - Specify the commit author's name
 - `content` (required) - New file content

doc/api/snippets.md

@@ -292,7 +292,7 @@ Parameters:
 | `description`         | string          | no       | Description of a snippet                                                            |
 | `visibility`          | string          | no       | Snippet's [visibility](#snippet-visibility-level)                                   |
 | `files`               | array of hashes | sometimes | An array of snippet files. Required when updating snippets with multiple files. |
-| `files:action`        | string          | yes      | Type of action to perform on the file, one of: 'create', 'update', 'delete', 'move' |
+| `files:action`        | string          | yes      | Type of action to perform on the file, one of: `create`, `update`, `delete`, `move` |
 | `files:file_path`     | string          | no       | File path of the snippet file                                                       |
 | `files:previous_path` | string          | no       | Previous path of the snippet file                                                   |
 | `files:content`       | string          | no       | Content of the snippet file                                                         |

spec/requests/api/discussions_spec.rb

@@ -68,18 +68,11 @@ RSpec.describe API::Discussions do
         mr_commit = '0b4bc9a49b562e85de7cc9e834518ea6828729b9'
         parent_commit = 'ae73cb07c9eeaf35924a10f713b364d32b2dd34f'
         file = "files/ruby/feature.rb"
-        line_range = {
-          "start_line_code" => Gitlab::Git.diff_line_code(file, 1, 1),
-          "end_line_code" => Gitlab::Git.diff_line_code(file, 1, 1),
-          "start_line_type" => "text",
-          "end_line_type" => "text"
-        }
         position = build(
           :text_diff_position,
           :added,
           file: file,
           new_line: 1,
-          line_range: line_range,
           base_sha: parent_commit,
           head_sha: mr_commit,
           start_sha: parent_commit