Document that comment range end line is inclusive
In practice, the behavior of Gerrit is that comment range end line
could be considered "inclusive" rather than "exclusive".
That is, we can have a non-empty comment where start line is equal
to end line. And if we have a comment that includes up to the end
of line 5996 but not including the newline, then end line is 5996,
not 5997.
This CL changes API documentation and updates comments.
Change-Id: Ia7ca464265315a6dfb5a30259fa1ac1592a1da61
diff --git a/Documentation/rest-api-changes.txt b/Documentation/rest-api-changes.txt
index fb0a0df..ff9635e 100644
--- a/Documentation/rest-api-changes.txt
+++ b/Documentation/rest-api-changes.txt
@@ -5996,13 +5996,22 @@
=== CommentRange
The `CommentRange` entity describes the range of an inline comment.
+The comment range is a range from the start position, specified by `start_line`
+and `start_character`, to the end position, specified by `end_line` and
+`end_character`. The start position is *inclusive* and the end position is
+*exclusive*.
+
+So, a range over part of a line will have `start_line` equal to
+`end_line`; however a range with `end_line` set to 5 and `end_character` equal
+to 0 will not include any characters on line 5,
+
[options="header",cols="1,^1,5"]
|===========================
-|Field Name ||Description
-|`start_line` ||The start line number of the range. (1-based, inclusive)
-|`start_character` ||The character position in the start line. (0-based, inclusive)
-|`end_line` ||The end line number of the range. (1-based, exclusive)
-|`end_character` ||The character position in the end line. (0-based, exclusive)
+|Field Name ||Description
+|`start_line` ||The start line number of the range. (1-based)
+|`start_character` ||The character position in the start line. (0-based)
+|`end_line` ||The end line number of the range. (1-based)
+|`end_character` ||The character position in the end line. (0-based)
|===========================
[[commit-info]]
diff --git a/java/com/google/gerrit/extensions/client/Comment.java b/java/com/google/gerrit/extensions/client/Comment.java
index 3307997..3bca4bb 100644
--- a/java/com/google/gerrit/extensions/client/Comment.java
+++ b/java/com/google/gerrit/extensions/client/Comment.java
@@ -44,10 +44,11 @@
.thenComparingInt(range -> range.endLine)
.thenComparingInt(range -> range.endCharacter);
- public int startLine; // 1-based, inclusive
- public int startCharacter; // 0-based, inclusive
- public int endLine; // 1-based, exclusive
- public int endCharacter; // 0-based, exclusive
+ // Start position is inclusive; end position is exclusive.
+ public int startLine; // 1-based
+ public int startCharacter; // 0-based
+ public int endLine; // 1-based
+ public int endCharacter; // 0-based
public boolean isValid() {
return startLine > 0
diff --git a/java/com/google/gerrit/reviewdb/client/CommentRange.java b/java/com/google/gerrit/reviewdb/client/CommentRange.java
index b9da8d5..3c69538 100644
--- a/java/com/google/gerrit/reviewdb/client/CommentRange.java
+++ b/java/com/google/gerrit/reviewdb/client/CommentRange.java
@@ -33,10 +33,11 @@
protected CommentRange() {}
public CommentRange(int sl, int sc, int el, int ec) {
- startLine = sl;
- startCharacter = sc;
- endLine = el;
- endCharacter = ec;
+ // Start position is inclusive; end position is exclusive.
+ startLine = sl; // 1-based
+ startCharacter = sc; // 0-based
+ endLine = el; // 1-based
+ endCharacter = ec; // 0-based
}
public int getStartLine() {
