Add warning for XML documentation comments not positioned as first non-whitespace on line

docs/release-notes/.FSharp.Compiler.Service/11.0.0.md

@@ -20,6 +20,7 @@
 * Add FSharpCodeCompletionOptions ([PR #19030](https://github.com/dotnet/fsharp/pull/19030))
 * Type checker: recover on checking binding parameter constraints ([#19046](https://github.com/dotnet/fsharp/pull/19046))
 * Debugger: provide breakpoint ranges for short lambdas ([#19067](https://github.com/dotnet/fsharp/pull/19067))
+* Add warning FS3879 for XML documentation comments not positioned as first non-whitespace on line. ([PR #18891](https://github.com/dotnet/fsharp/pull/18891))
 
 ### Changed
 

src/Compiler/Checking/infos.fs

@@ -1516,7 +1516,7 @@ type ILFieldInfo =
         match x with
         | ILFieldInfo(tinfo, _) -> tinfo.TypeInstOfRawMetadata
 #if !NO_TYPEPROVIDERS
-        | ProvidedField _ -> [] /// GENERIC TYPE PROVIDERS
+        | ProvidedField _ -> [] // GENERIC TYPE PROVIDERS
 #endif
 
      /// Get the name of the field

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

@@ -62,6 +62,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",
@@ -84,6 +88,8 @@ let mkLexargs
         stringNest = []
         pathMap = pathMap
         interpolationDelimiterLength = 0
+        lastTokenEndLine = 0
+        lastTokenEndColumn = 0
     }
 
 /// Register the lexbuf and call the given function
@@ -444,9 +450,16 @@ 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

@@ -29,15 +29,21 @@ type LexResourceManager =
 
 /// The context applicable to all lexing functions (tokens, strings etc.)
 type LexArgs =
-    { conditionalDefines: string list
-      resourceManager: LexResourceManager
-      diagnosticsLogger: DiagnosticsLogger
-      applyLineDirectives: bool
-      pathMap: PathMap
-      mutable ifdefStack: LexerIfdefStack
-      mutable indentationSyntaxStatus: IndentationAwareSyntaxStatus
-      mutable stringNest: LexerInterpolatedStringNesting
-      mutable interpolationDelimiterLength: int }
+    {
+        conditionalDefines: string list
+        resourceManager: LexResourceManager
+        diagnosticsLogger: DiagnosticsLogger
+        applyLineDirectives: bool
+        pathMap: PathMap
+        mutable ifdefStack: LexerIfdefStack
+        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
+    }
 
 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
 
@@ -412,6 +418,7 @@ rule token (args: LexArgs) (skip: bool) = parse
  | int
      { let s = removeUnderscores (lexeme lexbuf)
        // Allow <max_int+1> to parse as min_int.  Allowed only because we parse '-' as an operator.
+       updateLastTokenPos args lexbuf
        if Ranges.isInt32BadMax s then INT32(Int32.MinValue, true (* 'true' = 'bad'*) ) else
        let n =
            try int32 s with _ ->  fail args lexbuf (FSComp.SR.lexOutsideThirtyTwoBitSigned()) 0
@@ -422,6 +429,7 @@ rule token (args: LexArgs) (skip: bool) = parse
  | int32
      { let s = removeUnderscores (lexemeTrimRight lexbuf 1)
        // Allow <max_int+1> to parse as min_int.  Allowed only because we parse '-' as an operator.
+       updateLastTokenPos args lexbuf
        if Ranges.isInt32BadMax s then INT32(Int32.MinValue, true (* 'true' = 'bad'*) ) else
        let n =
            try int32 s with _ ->  fail args lexbuf (FSComp.SR.lexOutsideThirtyTwoBitSigned()) 0
@@ -484,10 +492,12 @@ rule token (args: LexArgs) (skip: bool) = parse
      }
 
  | ieee64
-     { IEEE64 (try float(lexeme lexbuf) with _ -> fail args lexbuf (FSComp.SR.lexInvalidFloat()) 0.0) }
+     { updateLastTokenPos args lexbuf
+       IEEE64 (try float(lexeme lexbuf) with _ -> fail args lexbuf (FSComp.SR.lexInvalidFloat()) 0.0) }
 
  | decimal
-     { try
+     { updateLastTokenPos args lexbuf
+       try
           let s = removeUnderscores (lexemeTrimRight lexbuf 1)
           // This implements a range check for decimal literals
           let d = System.Decimal.Parse(s,System.Globalization.NumberStyles.AllowExponent ||| System.Globalization.NumberStyles.Number,System.Globalization.CultureInfo.InvariantCulture)
@@ -740,6 +750,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 +866,7 @@ rule token (args: LexArgs) (skip: bool) = parse
 
  | '(' { LPAREN }
 
- | ')' { RPAREN }
+ | ')' { updateLastTokenPos args lexbuf; RPAREN }
 
  | '*' { STAR }
 
@@ -910,13 +924,13 @@ rule token (args: LexArgs) (skip: bool) = parse
 
  | "[<" { LBRACK_LESS }
 
- | "]" { RBRACK }
+ | "]" { updateLastTokenPos args lexbuf; RBRACK }
 
- | "|]" { BAR_RBRACK }
+ | "|]" { updateLastTokenPos args lexbuf; BAR_RBRACK }
 
- | "|}" { BAR_RBRACE }
+ | "|}" { updateLastTokenPos args lexbuf; BAR_RBRACE }
 
- | ">]" { GREATER_RBRACK }
+ | ">]" { updateLastTokenPos args lexbuf; GREATER_RBRACK }
 
  | "{"
      {
@@ -966,10 +980,12 @@ rule token (args: LexArgs) (skip: bool) = parse
            // will be reported w.r.t. the first '{'
            args.stringNest <- (counter - 1, style, d, altR, m) :: rest
            let cont = LexCont.Token(args.ifdefStack, args.stringNest)
+           updateLastTokenPos args lexbuf
            RBRACE cont
 
        | _ ->
            let cont = LexCont.Token(args.ifdefStack, args.stringNest)
+           updateLastTokenPos args lexbuf
            RBRACE cont
      }
 

tests/AheadOfTime/Trimming/FSharpMetadataResource_Trimming_Test/FSharpMetadataResource_Trimming_Test.fsproj

@@ -5,6 +5,7 @@
     <TargetFrameworks>net9.0</TargetFrameworks>
     <LangVersion>preview</LangVersion>
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <NoWarn>3879</NoWarn>
   </PropertyGroup>
 
   <PropertyGroup>

tests/AheadOfTime/Trimming/Program.fs

@@ -8262,7 +8262,7 @@ let func7000()=
     test "test7935" (lazy(sprintf "%+0G" -10.0M)) "-10"
     test "test7936" (lazy(sprintf "%+05G" -10.0M)) "-0010"//  "00-10"
     test "test7937" (lazy(sprintf "%+01G" -10.0M)) "-10"
-    test "test7938" (lazy(sprintf "%+0*G" 7 -10.0M)) "-000010"/// "0000-10"
+    test "test7938" (lazy(sprintf "%+0*G" 7 -10.0M)) "-000010"// "0000-10"
     test "test7939" (lazy(sprintf "%+0.5G" -10.0M)) "-10"
     test "test7940" (lazy(sprintf "%+0.*G" 4 -10.0M)) "-10"
     test "test7941" (lazy(sprintf "%+0*.*G" 5 4 -10.0M)) "-0010"// "00-10"

tests/AheadOfTime/Trimming/SelfContained_Trimming_Test/SelfContained_Trimming_Test.fsproj

@@ -5,6 +5,7 @@
     <TargetFrameworks>net9.0</TargetFrameworks>
     <LangVersion>preview</LangVersion>
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <NoWarn>3879</NoWarn>
   </PropertyGroup>
 
   <PropertyGroup>

tests/AheadOfTime/Trimming/StaticLinkedFSharpCore_Trimming_Test/StaticLinkedFSharpCore_Trimming_Test.fsproj

@@ -5,6 +5,7 @@
     <TargetFrameworks>net9.0</TargetFrameworks>
     <LangVersion>preview</LangVersion>
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <NoWarn>3879</NoWarn>
     <ProduceReferenceAssembly>false</ProduceReferenceAssembly>
     <OtherFlags>--standalone</OtherFlags>
   </PropertyGroup>