Discussion API, "Create new merge request thread" is underdocumented

Sufficiently document the "Create new merge request thread" request type of the Discussion API

As for now its documentation (https://docs.gitlab.com/ee/api/discussions.html#create-new-merge-request-thread) lacks some information crucial for its usage and missing pieces are not easy to guess (and are, to some extent, counter-intuitive).

Note: it is quite likely that some other request types from this API suffer from the same problem

Further details

It isn't specified, which combinations of position[new_path], position[old_path], position[new_line], position[old_line] attributes have to be provided in an request and to which values these attributes have to be set in following cases

added file,
deleted file,
renamed file,
added line,
deleted line,
unchanged line. Note, that settings required by this call are rather counter-intuitive and differ from what you may expect looking on an output of the standard git diff for these cases.

For example (position[] in attribute names is omitted for a sake of brevity):

for the newly added file you have to specify both new_path and old_path and set both of them to a path of the added file (while git diff shows old path as /dev/null, see below)

>git diff HEAD^
 diff --git a/added_file.txt b/added_file.txt
 new file mode 100644
 index 0000000..6dc0bf5
 --- /dev/null
 +++ b/added_file.txt
 @@ -0,0 +1 @@

for the deleted file it is essentially the same - you have to specify both new_path and old_path and to set both of them to the path of the file before deletion.
for the added (modified) line you have to set new_line, but must omit old_line (this approach is reasonable, but inconsistent with an approach to new_path / old_path for the added file).
for deleted line you must to omit new_line and have to specify old_line ((this approach is reasonable, but inconsistent with an approach to new_path / old_path for the deleted file).
for unchanged line you must to specify both old_line and new_line - while any of them uniquely identify another and so it isn't obvious that both to be specified.

Reactions on incorrect parameter values/combinations are not documented (and, as for now, they are inconsistent - a separate ticket will be created).

The documentation doesn't mention that abbreviated SHA-s aren't fully supported - while a comment is created exactly as in a case of full SHA-s it is not shown inline on the Changes tab of the merger request see sha-demo.bat, sha-demo.json, glapi-testbed.git.tgz and this screenshot

Proposal

Add this info to documentation (unless behavior would be fixed - a separate ticket will be created for it).

Discussion API, "Create new merge request thread" is underdocumented

Sufficiently document the "Create new merge request thread" request type of the Discussion API

Further details

Proposal

Who can address the issue

Other links/references