refactor(doclink): rearrange some doclink comment processing logic to make it easier to understand.

Author: cconstable

internal/client_testsuite.go

@@ -19,8 +19,6 @@ type (
 
 // NewTestClientEnvironment creates a new TestClientEnvironment with the given
 // interceptors chained before a no-op terminal interceptor.
-//
-// Exposed as: [go.temporal.io/sdk/testsuite.ClientTestSuite.NewTestClientEnvironment]
 func (s *ClientTestSuite) NewTestClientEnvironment(interceptors ...ClientInterceptor) *TestClientEnvironment {
 	var chain ClientOutboundInterceptor = &noopClientOutboundInterceptor{}
 	for _, interceptor := range interceptors {

internal/cmd/tools/doclink/doclink.go

@@ -390,10 +390,26 @@ func processInternal(cfg config, file *os.File, pairs map[string]map[string]stri
 			trimmedNextLine = nextLine
 		}
 
-		// Only check top-level definitions.
-		// Example: on a line like "func f() {", inFunc is still false here.
-		// Without the explicit func check, the next line could be treated like a top-level definition.
-		if !inFunc && !inInterface && !strings.HasPrefix(trimmedLine, "func ") && isValidDefinition(trimmedNextLine, &inGroup, &inStruct) {
+		// Track whether nextLine is inside a function or interface block.
+		// We update this first so the first line inside a block is not treated
+		// as a top-level definition.
+		if strings.HasPrefix(trimmedLine, "func ") {
+			funcSpaces = indentSize
+			inFunc = true
+		} else if inFunc && trimmedLine == "}" && funcSpaces == indentSize {
+			funcSpaces = -1
+			inFunc = false
+		}
+		if strings.HasSuffix(trimmedLine, "interface {") {
+			interfaceSpaces = indentSize
+			inInterface = true
+		} else if inInterface && trimmedLine == "}" && interfaceSpaces == indentSize {
+			interfaceSpaces = -1
+			inInterface = false
+		}
+
+		// Check for new doc links to add on top-level definitions only.
+		if !inFunc && !inInterface && isValidDefinition(trimmedNextLine, &inGroup, &inStruct) {
 			// Find the "Exposed As" line in the doc comment
 			var existingDoclink string
 			comScanner := bufio.NewScanner(strings.NewReader(commentBlock))
@@ -453,23 +469,6 @@ func processInternal(cfg config, file *os.File, pairs map[string]map[string]stri
 			}
 		}
 
-		// update inFunc after we actually check for doclinks to allow us to check
-		// a function's definition, without checking anything inside the function
-		if strings.HasPrefix(trimmedLine, "func ") {
-			funcSpaces = indentSize
-			inFunc = true
-		} else if inFunc && trimmedLine == "}" && funcSpaces == indentSize {
-			funcSpaces = -1
-			inFunc = false
-		}
-		if strings.HasSuffix(trimmedLine, "interface {") {
-			interfaceSpaces = indentSize
-			inInterface = true
-		} else if inInterface && trimmedLine == "}" && interfaceSpaces == indentSize {
-			interfaceSpaces = -1
-			inInterface = false
-		}
-
 		newFile += line + "\n"
 	}