Skip to content

Improve API docs for multi-line comments

Is it possible to create a discussion on MR diff (a note with a position) with the REST API? @viktomas ran into this problem several months ago in !51032 and thought it was not possible, but @krobelus noted in the next comment that it was under-documented.

!51525 (comment 524428578) sought to document it, but in that issue @garyh noted the parameter position[line_range][end][line_code] was unnecessarily complex and didn't fit well in the table. He created #323760 (closed) to seek a better approach, but until the API is less frustrating, we could get a code example and an explanation in place.

@viktomas and @krobelus - thank you for your explanations across multiple issues. While not new to GitLab, I am new to devopscreate, and your explanations helped me pull together this docs-specific issue. Hopefully, we can spare others the frustration you encountered.

Intention

  • Create a new subheading in doc/api/discussions.md.

  • It should provide an example of how to create discussion on a merge request diff (a note with a position) with the REST API.

  • Extract the contents of this long line (roughly line 865) and incorporate it into the new subheading:

    | `position[line_range][end][line_code]`   | string         | yes, for multiple lines | SHA1 hash of the filename, followed by '_', the line number before the change, '_', and the line number after the change. Example: when commenting on an added line number 5, this should be something like 'adc83b19e793491b1c6ea0fd8b46cd9f32e292fc_5_5'.  |

  • Crosslink from the table row to this new subheading, to keep the table tidy AND provide more information.

I'm routing this request over to @garyh first, because I need the code example to get started. Gary, when you have something created, add it in as a comment to this issue, and reassign this issue to me so I know I can start my portion of the work.

Citations

  • Related to #247521 (closed) ("Docs feedback: Create new merge request thread (discussions api) is missing important information for position[line_range] ")
  • Related to #219215 (closed) ("Cannot create new merge request thread via API v4")
  • Related to #323760 (closed) where Gary has proposed finding a better approach for line_code for positions.
  • Related to #281143 (closed) ("MR Diff REST API - creating note causes 500 and shows strange web UI")
  • Related to #296829 (closed) ("Merge request comments receive "download" link instead of inline code")