Re-implement XML doc comment position warning using token position tracking

- Add lastTokenEndLine and lastTokenEndColumn fields to LexArgs
- Track token positions in KeywordOrIdentifierToken and IdentifierToken
- Add updateLastTokenPos helper function in lexer
- Check position when /// is lexed and warn if on same line as previous token
- Add FSComp.txt entry 3879 for the warning message

Co-authored-by: T-Gro <[email protected]>

Author: Copilot

src/Compiler/FSComp.txt

@@ -1813,4 +1813,5 @@ featureAllowLetOrUseBangTypeAnnotationWithoutParens,"Allow let! and use! type an
 3876,lexWarnDirectivesMustMatch,"There is another %s for this warning already in line %d."
 3877,lexLineDirectiveMappingIsNotUnique,"The file '%s' was also pointed to in a line directive in '%s'. Proper warn directive application may not be possible."
 3878,tcAttributeIsNotValidForUnionCaseWithFields,"This attribute is not valid for use on union cases with fields."
+3879,xmlDocNotFirstOnLine,"XML documentation comments should be the first non-whitespace text on a line."
 featureReturnFromFinal,"Support for ReturnFromFinal/YieldFromFinal in computation expressions to enable tailcall optimization when available on the builder."

src/Compiler/SyntaxTree/LexHelpers.fs

@@ -63,6 +63,10 @@ type LexArgs =
         mutable indentationSyntaxStatus: IndentationAwareSyntaxStatus
         mutable stringNest: LexerInterpolatedStringNesting
         mutable interpolationDelimiterLength: int
+        /// Tracks the line number of the last non-whitespace, non-comment token
+        mutable lastTokenEndLine: int
+        /// Tracks the end column of the last non-whitespace, non-comment token
+        mutable lastTokenEndColumn: int
     }
 
 /// possible results of lexing a long Unicode escape sequence in a string literal, e.g. "\U0001F47D",
@@ -85,6 +89,8 @@ let mkLexargs
         stringNest = []
         pathMap = pathMap
         interpolationDelimiterLength = 0
+        lastTokenEndLine = 0
+        lastTokenEndColumn = 0
     }
 
 /// Register the lexbuf and call the given function
@@ -445,9 +451,15 @@ module Keywords =
         if IsCompilerGeneratedName s then
             warning (Error(FSComp.SR.lexhlpIdentifiersContainingAtSymbolReserved (), lexbuf.LexemeRange))
 
+        // Track token position for XML doc comment checking
+        args.lastTokenEndLine <- lexbuf.EndPos.Line
+        args.lastTokenEndColumn <- lexbuf.EndPos.Column
         args.resourceManager.InternIdentifierToken s
 
     let KeywordOrIdentifierToken args (lexbuf: Lexbuf) s =
+        // Track token position for XML doc comment checking
+        args.lastTokenEndLine <- lexbuf.EndPos.Line
+        args.lastTokenEndColumn <- lexbuf.EndPos.Column
         match keywordTable.TryGetValue s with
         | true, v ->
             match v with

src/Compiler/SyntaxTree/LexHelpers.fsi

@@ -37,7 +37,11 @@ type LexArgs =
       mutable ifdefStack: LexerIfdefStack
       mutable indentationSyntaxStatus: IndentationAwareSyntaxStatus
       mutable stringNest: LexerInterpolatedStringNesting
-      mutable interpolationDelimiterLength: int }
+      mutable interpolationDelimiterLength: int
+      /// Tracks the line number of the last non-whitespace, non-comment token
+      mutable lastTokenEndLine: int
+      /// Tracks the end column of the last non-whitespace, non-comment token  
+      mutable lastTokenEndColumn: int }
 
 type LongUnicodeLexResult =
     | SurrogatePair of uint16 * uint16

src/Compiler/lex.fsl

@@ -54,6 +54,12 @@ let fail args (lexbuf:UnicodeLexing.Lexbuf) msg dflt =
      args.diagnosticsLogger.ErrorR(Error(msg,m))
      dflt
 
+/// Update tracking of the last token position for XML doc comment position checking
+let updateLastTokenPos (args: LexArgs) (lexbuf: UnicodeLexing.Lexbuf) =
+    let endPos = lexbuf.EndPos
+    args.lastTokenEndLine <- endPos.Line
+    args.lastTokenEndColumn <- endPos.Column
+
 //--------------------------
 // Integer parsing
 
@@ -740,6 +746,10 @@ rule token (args: LexArgs) (skip: bool) = parse
  | "///" op_char*
      { // Match exactly 3 slash, 4+ slash caught by preceding rule
        let m = lexbuf.LexemeRange
+       // Check if there was a token on this line before this /// comment
+       // If lastTokenEndLine matches the current line, there's code before the comment
+       if args.lastTokenEndLine = m.StartLine then
+           warning (Error(FSComp.SR.xmlDocNotFirstOnLine(), m))
        let doc = lexemeTrimLeft lexbuf 3
        let sb = (new StringBuilder(100)).Append(doc)
        if not skip then LINE_COMMENT (LexCont.SingleLineComment(args.ifdefStack, args.stringNest, 1, m))
@@ -852,7 +862,7 @@ rule token (args: LexArgs) (skip: bool) = parse
 
  | '(' { LPAREN }
 
- | ')' { RPAREN }
+ | ')' { updateLastTokenPos args lexbuf; RPAREN }
 
  | '*' { STAR }