Update documentation to reflect actual implementation and adapt usage accordingly

Author: knutwalker

algo/src/main/java/org/neo4j/gds/triangle/intersect/GraphIntersect.java

@@ -126,15 +126,25 @@ public void intersectAll(long nodeA, IntersectionConsumer consumer) {
                     if (neighboursB.hasNextVLong()) {
                         // we take the next neighbour Cb of B with id >= Ca
                         nodeCFromB = neighboursB.advance(nodeCFromA);
-                        if (degreeFilter.test(degree(nodeCFromB))) {
-                            checkForAndEmitTriangle(consumer, nodeA, nodeB, nodeCFromA, nodeCFromB, triangleC);
+                        // B had some more nodes, but none of them were >= Ca, so we skip it
+                        if (nodeCFromB != NOT_FOUND) {
+                            var degreeCFromB = degree(nodeCFromB);
+
+                            if (degreeFilter.test(degreeCFromB)) {
+                                checkForAndEmitTriangle(consumer, nodeA, nodeB, nodeCFromA, nodeCFromB, triangleC);
+                            }
                         }
                     }
                 }
             }
 
             // skip until the next neighbour B of A with id > (current) B
             nodeB = neighboursAMain.skipUntil(nodeB);
+
+            // There are no more neighbors that are relevant to us
+            if (nodeB == NOT_FOUND) {
+                return;
+            }
         }
 
         cacheA = neighboursA;
@@ -151,6 +161,7 @@ private long checkForAndEmitTriangle(
     ) {
         // if Ca = Cb there exists a triangle
         // if Ca = triangleC we have already counted it
+        // Ca might also be NOT_FOUND, we ignore those as well
         if (nodeCa == nodeCb && nodeCa > triangleC) {
             consumer.accept(nodeA, nodeB, nodeCa);
             return nodeCa;

core/src/main/java/org/neo4j/gds/api/AdjacencyCursor.java

@@ -71,23 +71,15 @@ public interface AdjacencyCursor extends AutoCloseable {
      */
     int remaining();
 
-    // DOCTODO: I think this documentation if either out of date or misleading.
-    //  Either we skip all blocks and return -1 or we find a value that is strictly larger.
     /**
      * Read and decode target ids until it is strictly larger than ({@literal >}) the provided {@code target}.
-     * Might return an id that is less than or equal to {@code target} iff the cursor did exhaust before finding an
-     * id that is large enough.
-     * {@code skipUntil(target) <= target} can be used to distinguish the no-more-ids case and afterwards {@link #hasNextVLong()}
-     * will return {@code false}
+     * If there are no such targets before this cursor is exhausted, {@link org.neo4j.gds.api.AdjacencyCursor#NOT_FOUND -1} is returned.
      */
     long skipUntil(long nodeId);
 
     /**
      * Read and decode target ids until it is larger than or equal ({@literal >=}) the provided {@code target}.
-     * Might return an id that is less than {@code target} iff the cursor did exhaust before finding an
-     * id that is large enough.
-     * {@code advance(target) < target} can be used to distinguish the no-more-ids case and afterwards {@link #hasNextVLong()}
-     * will return {@code false}
+     * If there are no such targets before this cursor is exhausted, {@link org.neo4j.gds.api.AdjacencyCursor#NOT_FOUND -1} is returned.
      */
     long advance(long nodeId);
 

core/src/main/java/org/neo4j/gds/core/huge/TransientCompressedList.java

@@ -213,14 +213,9 @@ public long peekVLong() {
             return decompress.peek(remaining);
         }
 
-        // TODO: I think this documentation if either out of date or misleading.
-        //  Either we skip all blocks and return -1 or we find a value that is strictly larger.
         /**
          * Read and decode target ids until it is strictly larger than ({@literal >}) the provided {@code target}.
-         * Might return an id that is less than or equal to {@code target} iff the cursor did exhaust before finding an
-         * id that is large enough.
-         * {@code skipUntil(target) <= target} can be used to distinguish the no-more-ids case and afterwards {@link #hasNextVLong()}
-         * will return {@code false}
+         * If there are no such targets before this cursor is exhausted, {@link org.neo4j.gds.api.AdjacencyCursor#NOT_FOUND -1} is returned.
          */
         @Override
         public long skipUntil(long target) {
@@ -231,10 +226,7 @@ public long skipUntil(long target) {
 
         /**
          * Read and decode target ids until it is larger than or equal ({@literal >=}) the provided {@code target}.
-         * Might return an id that is less than {@code target} iff the cursor did exhaust before finding an
-         * id that is large enough.
-         * {@code advance(target) < target} can be used to distinguish the no-more-ids case and afterwards {@link #hasNextVLong()}
-         * will return {@code false}
+         * If there are no such targets before this cursor is exhausted, {@link org.neo4j.gds.api.AdjacencyCursor#NOT_FOUND -1} is returned.
          */
         @Override
         public long advance(long target) {