Annotate multiline TODO comments (#924)

* annotate multiline TODO comments

* Revert "annotate multiline TODO comments"

This reverts commit 8af2a6f.

* undo vender/* updates

* revert more vender/* udpates

* move comments into exported functions

Author: prestonvasquez

bson/bsonrw/value_reader.go

@@ -86,12 +86,11 @@ type valueReader struct {
 
 // NewBSONDocumentReader returns a ValueReader using b for the underlying BSON
 // representation. Parameter b must be a BSON Document.
-//
-// TODO(skriptble): There's a lack of symmetry between the reader and writer, since the reader takes
-// a []byte while the writer takes an io.Writer. We should have two versions of each, one that takes
-// a []byte and one that takes an io.Reader or io.Writer. The []byte version will need to return a
-// thing that can return the finished []byte since it might be reallocated when appended to.
 func NewBSONDocumentReader(b []byte) ValueReader {
+	// TODO(skriptble): There's a lack of symmetry between the reader and writer, since the reader takes a []byte while the
+	// TODO writer takes an io.Writer. We should have two versions of each, one that takes a []byte and one that takes an
+	// TODO io.Reader or io.Writer. The []byte version will need to return a thing that can return the finished []byte since
+	// TODO it might be reallocated when appended to.
 	return newValueReader(b)
 }
 

mongo/integration/collection_test.go

@@ -137,8 +137,8 @@ func TestCollection(t *testing.T) {
 			assert.Equal(mt, want2, res.InsertedIDs[2], "expected inserted ID %v, got %v", want2, res.InsertedIDs[2])
 		})
 		mt.Run("batches", func(mt *mtest.T) {
-			// TODO(GODRIVER-425): remove this as part a larger project to
-			// refactor integration and other longrunning tasks.
+			// TODO(GODRIVER-425): remove this as part a larger project to refactor integration and other longrunning
+			// TODO tasks.
 			if os.Getenv("EVR_TASK_ID") == "" {
 				mt.Skip("skipping long running integration test outside of evergreen")
 			}
@@ -167,8 +167,8 @@ func TestCollection(t *testing.T) {
 			assert.Equal(mt, numDocs, len(res.InsertedIDs), "expected %v inserted IDs, got %v", numDocs, len(res.InsertedIDs))
 		})
 		mt.Run("large document batches", func(mt *mtest.T) {
-			// TODO(GODRIVER-425): remove this as part a larger project to
-			// refactor integration and other longrunning tasks.
+			// TODO(GODRIVER-425): remove this as part a larger project to refactor integration and other longrunning
+			// TODO tasks.
 			if os.Getenv("EVR_TASK_ID") == "" {
 				mt.Skip("skipping long running integration test outside of evergreen")
 			}
@@ -249,8 +249,8 @@ func TestCollection(t *testing.T) {
 			}
 		})
 		mt.Run("writeError index", func(mt *mtest.T) {
-			// TODO(GODRIVER-425): remove this as part a larger project to
-			// refactor integration and other longrunning tasks.
+			// TODO(GODRIVER-425): remove this as part a larger project to refactor integration and other longrunning
+			// TODO tasks.
 			if os.Getenv("EVR_TASK_ID") == "" {
 				mt.Skip("skipping long running integration test outside of evergreen")
 			}

mongo/integration/mtest/mongotest.go

@@ -268,9 +268,9 @@ func (t *T) ClearMockResponses() {
 
 // GetStartedEvent returns the most recent CommandStartedEvent, or nil if one is not present.
 // This can only be called once per event.
-// TODO(GODRIVER-2075): GetStartedEvent documents that it returns the most recent event, but
-// actually returns the first event. Update either the documentation or implementation.
 func (t *T) GetStartedEvent() *event.CommandStartedEvent {
+	// TODO(GODRIVER-2075): GetStartedEvent documents that it returns the most recent event, but actually returns the first
+	// TODO event. Update either the documentation or implementation.
 	if len(t.started) == 0 {
 		return nil
 	}
@@ -281,9 +281,9 @@ func (t *T) GetStartedEvent() *event.CommandStartedEvent {
 
 // GetSucceededEvent returns the most recent CommandSucceededEvent, or nil if one is not present.
 // This can only be called once per event.
-// TODO(GODRIVER-2075): GetSucceededEvent documents that it returns the most recent event, but
-// actually returns the first event. Update either the documentation or implementation.
 func (t *T) GetSucceededEvent() *event.CommandSucceededEvent {
+	// TODO(GODRIVER-2075): GetSucceededEvent documents that it returns the most recent event, but actually returns the
+	// TODO first event. Update either the documentation or implementation.
 	if len(t.succeeded) == 0 {
 		return nil
 	}
@@ -294,9 +294,9 @@ func (t *T) GetSucceededEvent() *event.CommandSucceededEvent {
 
 // GetFailedEvent returns the most recent CommandFailedEvent, or nil if one is not present.
 // This can only be called once per event.
-// TODO(GODRIVER-2075): GetFailedEvent documents that it returns the most recent event, but actually
-// returns the first event. Update either the documentation or implementation.
 func (t *T) GetFailedEvent() *event.CommandFailedEvent {
+	// TODO(GODRIVER-2075): GetFailedEvent documents that it returns the most recent event, but actually  returns the first
+	// TODO event. Update either the documentation or implementation.
 	if len(t.failed) == 0 {
 		return nil
 	}

mongo/integration/unified/testrunner_operation.go

@@ -236,8 +236,8 @@ func executeLoop(ctx context.Context, args *loopArgs, loopDone <-chan struct{})
 					case !args.failuresStored(): // store failures as errors if storeFailuressAsEntity isn't specified
 						appendErr = entityMap.appendBSONArrayEntity(args.ErrorsEntityID, errDoc)
 					// errors are test runner errors
-					// TODO GODRIVER-1950: use error types to determine error vs failure instead of depending on the fact that
-					// operation.execute prepends "execution failed" to test runner errors
+					// TODO GODRIVER-1950: use error types to determine error vs failure instead of depending on the
+					// TODO fact that operation.execute prepends "execution failed" to test runner errors
 					case strings.Contains(loopErr.Error(), "execution failed: "):
 						appendErr = entityMap.appendBSONArrayEntity(args.ErrorsEntityID, errDoc)
 					// failures are if an operation returns an incorrect result or error

x/bsonx/bsoncore/bsoncore.go

@@ -65,8 +65,7 @@ func AppendHeader(dst []byte, t bsontype.Type, key string) []byte {
 	// return append(AppendType(dst, t), key+string(0x00)...)
 }
 
-// TODO(skriptble): All of the Read* functions should return src resliced to start just after what
-// was read.
+// TODO(skriptble): All of the Read* functions should return src resliced to start just after what was read.
 
 // ReadType will return the first byte of the provided []byte as a type. If
 // there is no available byte, false is returned.
@@ -197,12 +196,13 @@ func ReadString(src []byte) (string, []byte, bool) {
 
 // AppendDocumentStart reserves a document's length and returns the index where the length begins.
 // This index can later be used to write the length of the document.
-//
-// TODO(skriptble): We really need AppendDocumentStart and AppendDocumentEnd.
-// AppendDocumentStart would handle calling ReserveLength and providing the index of the start of
-// the document. AppendDocumentEnd would handle taking that start index, adding the null byte,
-// calculating the length, and filling in the length at the start of the document.
-func AppendDocumentStart(dst []byte) (index int32, b []byte) { return ReserveLength(dst) }
+func AppendDocumentStart(dst []byte) (index int32, b []byte) {
+	// TODO(skriptble): We really need AppendDocumentStart and AppendDocumentEnd.  AppendDocumentStart would handle calling
+	// TODO ReserveLength and providing the index of the start of the document. AppendDocumentEnd would handle taking that
+	// TODO start index, adding the null byte, calculating the length, and filling in the length at the start of the
+	// TODO document.
+	return ReserveLength(dst)
+}
 
 // AppendDocumentStartInline functions the same as AppendDocumentStart but takes a pointer to the
 // index int32 which allows this function to be used inline.

x/mongo/driver/driver.go

@@ -214,11 +214,11 @@ func (ssd SingleConnectionDeployment) MinRTT() time.Duration {
 	return 0
 }
 
-// TODO(GODRIVER-617): We can likely use 1 type for both the Type and the RetryMode by using
-// 2 bits for the mode and 1 bit for the type. Although in the practical sense, we might not want to
-// do that since the type of retryability is tied to the operation itself and isn't going change,
-// e.g. and insert operation will always be a write, however some operations are both reads and
-// writes, for instance aggregate is a read but with a $out parameter it's a write.
+// TODO(GODRIVER-617): We can likely use 1 type for both the Type and the RetryMode by using 2 bits for the mode and 1
+// TODO bit for the type. Although in the practical sense, we might not want to do that since the type of retryability
+// TODO is tied to the operation itself and isn't going change, e.g. and insert operation will always be a write,
+// TODO however some operations are both reads and  writes, for instance aggregate is a read but with a $out parameter
+// TODO it's a write.
 
 // Type specifies whether an operation is a read, write, or unknown.
 type Type uint

x/mongo/driver/mongocrypt/mongocrypt_test.go

@@ -127,8 +127,8 @@ func testKmsCtx(t *testing.T, ctx *Context, keyAltName bool) {
 	hostname, err := kmsCtx.HostName()
 	noerr(t, err)
 
-	// TODO GODRIVER-2217: Simply check if hostname != expectedHost once all OSes build the latest
-	// libmongocrypt versions.
+	// TODO GODRIVER-2217: Simply check if hostname != expectedHost once all OSes build the latest libmongocrypt
+	// TODO versions.
 	//
 	// Only check for the hostname. libmongocrypt versions that do not include MONGOCRYPT-352 will not
 	// include the default port "443".

x/mongo/driver/operation.go

@@ -1265,8 +1265,8 @@ func (op Operation) getReadPrefBasedOnTransaction() (*readpref.ReadPref, error)
 }
 
 func (op Operation) createReadPref(desc description.SelectedServer, isOpQuery bool) (bsoncore.Document, error) {
-	// TODO(GODRIVER-2231): Instead of checking if isOutputAggregate and desc.Server.WireVersion.Max < 13,
-	// somehow check if supplied readPreference was "overwritten" with primary in description.selectForReplicaSet.
+	// TODO(GODRIVER-2231): Instead of checking if isOutputAggregate and desc.Server.WireVersion.Max < 13, somehow check
+	// TODO if supplied readPreference was "overwritten" with primary in description.selectForReplicaSet.
 	if desc.Server.Kind == description.Standalone || (isOpQuery && desc.Server.Kind != description.Mongos) ||
 		op.Type == Write || (op.IsOutputAggregate && desc.Server.WireVersion.Max < 13) {
 		// Don't send read preference for:

x/mongo/driver/topology/CMAP_spec_test.go

@@ -39,25 +39,24 @@ var skippedTestDescriptions = map[string]string{
 	// asserts that handshake errors trigger events "connection closed" then "pool cleared". The Go
 	// driver uses the same code path for creating all application connections, so those opposing
 	// event orders cannot be satisfied simultaneously.
-	// TODO(DRIVERS-1785): Re-enable this test once the spec test is updated to use the same event
-	// order as the "errors during authentication are processed" load-balancer SDAM spec test.
+	// TODO(DRIVERS-1785): Re-enable this test once the spec test is updated to use the same event order as the "errors
+	// TODO during authentication are processed" load-balancer SDAM spec test.
 	"error during minPoolSize population clears pool": "event ordering is incompatible with load-balancer SDAM spec test (DRIVERS-1785)",
 	// GODRIVER-1826: The Go connection pool does not currently always deliver connections created
 	// by maintain() to waiting check-outs. There is a race condition between the goroutine started
 	// by maintain() to check-in a requested connection and createConnections() picking up the next
 	// wantConn created by the waiting check-outs. Most of the time, createConnections() wins and
 	// starts creating new connections. That is not a problem for general use cases, but it prevents
 	// the "threads blocked by maxConnecting check out minPoolSize connections" test from passing.
-	// TODO(DRIVERS-2225): Re-enable this test once the spec test is updated to support the Go pool
-	// minPoolSize maintain() behavior.
+	// TODO(DRIVERS-2225): Re-enable this test once the spec test is updated to support the Go pool minPoolSize
+	// TODO maintain() behavior.
 	"threads blocked by maxConnecting check out minPoolSize connections": "test requires that connections established by minPoolSize are immediately used to satisfy check-out requests (DRIVERS-2225)",
 	// GODRIVER-1826: The Go connection pool currently delivers any available connection to the
 	// earliest waiting check-out request, independent of if that check-out request already
 	// requested a new connection. That behavior is currently incompatible with the "threads blocked
 	// by maxConnecting check out returned connections" test, which expects that check-out requests
 	// that request a new connection cannot be satisfied by a check-in.
-	// TODO(DRIVERS-2223): Re-enable this test once the spec test is updated to support the Go pool
-	// check-in behavior.
+	// TODO(DRIVERS-2223): Re-enable this test once the spec test is updated to support the Go pool check-in behavior.
 	"threads blocked by maxConnecting check out returned connections": "test requires a checked-in connections cannot satisfy a check-out waiting on a new connection (DRIVERS-2223)",
 }
 

x/mongo/driver/topology/topology_test.go

@@ -774,8 +774,8 @@ func runInWindowTest(t *testing.T, directory string, filename string) {
 		}
 
 		// Otherwise, check if the expected frequency is within the given tolerance range.
-		// TODO(GODRIVER-2179): Use assert.Deltaf() when we migrate all test code to the
-		// "testify/assert" or an API-compatible library for assertions.
+		// TODO(GODRIVER-2179): Use assert.Deltaf() when we migrate all test code to the "testify/assert" or an
+		// TODO API-compatible library for assertions.
 		low := expected - test.Outcome.Tolerance
 		high := expected + test.Outcome.Tolerance
 		assert.True(