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

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

@@ -6,6 +6,7 @@
 ### Added
 
 * FSharpDiagnostic: add default severity ([#19152](https://github.com/dotnet/fsharp/pull/19152))
+* Add warning FS3879 for XML documentation comments not positioned as first non-whitespace on line. ([PR #18891](https://github.com/dotnet/fsharp/pull/18891))
 
 ### Breaking Changes
 

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/LexFilter.fs

@@ -673,6 +673,14 @@
         savedLexbufState <- tokenLexbufState
         haveLexbufState <- true
 
+        // Track the last non-comment token position for XML doc comment validation
+        match token with
+        | LINE_COMMENT _ -> ()
+        | BLOCK_COMMENT _
+        | BLOCK_COMMENT_OPEN
+        | WHITESPACE _ -> ()
+        | _ -> XmlDocStore.SetLastNonCommentTokenLine lexbuf tokenLexbufState.EndPos.Line
+
         let tokenTup = pool.Rent()
         tokenTup.Token <- token
         tokenTup.LexbufState <- tokenLexbufState
@@ -2628,6 +2636,17 @@
         true
 
     and rulesForBothSoftWhiteAndHardWhite(tokenTup: TokenTup) =
+          // Check if XML doc comment (///) appears after other code on the same line
+          match tokenTup.Token with
+          | LINE_COMMENT comment when comment.StartsWithOrdinal("///") ->
+              let commentStartLine = tokenTup.StartPos.Line
+              let lastNonCommentLine = XmlDocStore.GetLastNonCommentTokenLine lexbuf
+              if lastNonCommentLine = commentStartLine then
+                  // XML doc comment appears on same line as previous non-comment token
+                  let m = mkFileIndexRange tokenTup.LexbufState.FileIndex tokenTup.StartPos (tokenTup.StartPos.ShiftColumnBy(3))
+                  warning(Error(FSComp.SR.xmlDocNotFirstOnLine(), m))
+          | _ -> ()
+
           match tokenTup.Token with
           | HASH_IDENT ident ->
               let hashPos = LexbufState(tokenTup.StartPos, tokenTup.StartPos.ShiftColumnBy(1), false)

src/Compiler/SyntaxTree/LexHelpers.fs

@@ -6,6 +6,7 @@
 open System.Text
 
 open Internal.Utilities
+open Internal.Utilities.Library
 open Internal.Utilities.Text.Lexing
 
 open FSharp.Compiler.DiagnosticsLogger
@@ -395,7 +396,7 @@
             (*------- for prototyping and explaining offside rule *)
             FSHARP, "__token_OBLOCKSEP", OBLOCKSEP
             FSHARP, "__token_OWITH", OWITH
-            FSHARP, "__token_ODECLEND", ODECLEND(range0, false)
+            FSHARP, "__token_ODECLEND", ODECLEND range0
             FSHARP, "__token_OTHEN", OTHEN
             FSHARP, "__token_OELSE", OELSE
             FSHARP, "__token_OEND", OEND
@@ -451,7 +452,7 @@
         | true, v ->
             match v with
             | RESERVED ->
-                warning (ReservedKeyword(FSComp.SR.lexhlpIdentifierReserved s, lexbuf.LexemeRange))
+                warning (ReservedKeyword(FSComp.SR.lexhlpIdentifierReserved (s), lexbuf.LexemeRange))
                 IdentifierToken args lexbuf s
             | _ ->
                 match s with
@@ -462,7 +463,7 @@
                 | "lsr"
                 | "asr" ->
                     if lexbuf.SupportsFeature LanguageFeature.MLCompatRevisions then
-                        mlCompatWarning (FSComp.SR.mlCompatKeyword s) lexbuf.LexemeRange
+                        mlCompatWarning (FSComp.SR.mlCompatKeyword (s)) lexbuf.LexemeRange
                 | _ -> ()
 
                 v

src/Compiler/SyntaxTree/LexerStore.fs

@@ -64,6 +64,14 @@
         let collector = getCollector lexbuf
         collector.CheckInvalidXmlDocPositions()
 
+    let SetLastNonCommentTokenLine (lexbuf: Lexbuf) (line: int) =
+        let collector = getCollector lexbuf
+        collector.SetLastNonCommentTokenLine(line)
+
+    let GetLastNonCommentTokenLine (lexbuf: Lexbuf) =
+        let collector = getCollector lexbuf
+        collector.LastNonCommentTokenLine
+
 //------------------------------------------------------------------------
 // Storage to hold the current accumulated ConditionalDirectiveTrivia, and related types and access functions
 //------------------------------------------------------------------------

src/Compiler/SyntaxTree/XmlDoc.fs

@@ -131,6 +131,7 @@ type XmlDocCollector() =
     let mutable savedGrabPoints = Dictionary<pos, struct (int * int * bool)>()
     let mutable currentGrabPointCommentsCount = 0
     let mutable delayedGrabPoint = ValueNone
+    let mutable lastNonCommentTokenLine = 0
 
     member _.AddGrabPoint(pos: pos) =
         if currentGrabPointCommentsCount = 0 then
@@ -187,6 +188,11 @@ type XmlDocCollector() =
     member _.HasComments grabPointPos =
         savedGrabPoints.TryGetValue grabPointPos |> fst
 
+    member _.SetLastNonCommentTokenLine(line: int) =
+        lastNonCommentTokenLine <- line
+
+    member _.LastNonCommentTokenLine = lastNonCommentTokenLine
+
     member _.CheckInvalidXmlDocPositions() =
         let comments = ResizeArray<range>(savedLines.Count)
 

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>