cknitt · Oct 23, 2026 · Oct 23, 2026
diff --git a/analysis/src/process_attributes.ml b/analysis/src/process_attributes.ml
@@ -4,7 +4,7 @@ open Shared_types
 let rec find_doc_attribute attributes =
   match attributes with
   | [] -> None
-  | ({Asttypes.txt = "ocaml.doc" | "ns.doc" | "res.doc"}, payload) :: rest -> (
+  | ({Asttypes.txt = "res.doc"}, payload) :: rest -> (
     match Ast_payload.semantic_string_of_payload payload with
     | Some doc -> Some doc
     | None -> find_doc_attribute rest)

diff --git a/changes/res-doc-only.breaking.md b/changes/res-doc-only.breaking.md
@@ -0,0 +1 @@
+- Editor hover, completion and `rescript-tools doc` read doc comments only from `/** */` comments (`@res.doc`); the legacy `@ocaml.doc` and `@ns.doc` attributes are no longer shown. Replace them with doc comments.
diff --git a/tests/analysis_tests/tests-reanalyze/deadcode/expected/deadcode.txt b/tests/analysis_tests/tests-reanalyze/deadcode/expected/deadcode.txt
@@ -2536,7 +2536,7 @@
   toArray is never used
 
   Warning Dead Value
-  ImmutableArray.resi:14:1-107
+  ImmutableArray.resi:14:1-105
   length is never used
 
   Warning Dead Value

diff --git a/tests/analysis_tests/tests-reanalyze/deadcode/src/ComponentAsProp.res b/tests/analysis_tests/tests-reanalyze/deadcode/src/ComponentAsProp.res
@@ -1,4 +1,4 @@
-@ocaml.doc(
+@res.doc(
   " This is like declaring a normal ReasonReact component's `make` function, except the body is a the interop hook wrapJsForReason "
 )
 @genType

diff --git a/tests/analysis_tests/tests-reanalyze/deadcode/src/Docstrings.res b/tests/analysis_tests/tests-reanalyze/deadcode/src/Docstrings.res
@@ -1,7 +1,7 @@
-@ocaml.doc(" hello ") @genType
+@res.doc(" hello ") @genType
 let flat = 34
 
-@ocaml.doc("
+@res.doc("
   * Sign a message with a key.
   *
   * @param message - A message to be signed

diff --git a/tests/analysis_tests/tests-reanalyze/deadcode/src/ImmutableArray.resi b/tests/analysis_tests/tests-reanalyze/deadcode/src/ImmutableArray.resi
@@ -1,17 +1,17 @@
-@ocaml.doc(" Immutable arrays are covariant. ")
+@res.doc(" Immutable arrays are covariant. ")
 type t<+'a>
 
-@ocaml.doc(" Redefine the [_] syntax, and disable the assignment [_] = _. ")
+@res.doc(" Redefine the [_] syntax, and disable the assignment [_] = _. ")
 module Array: {
   let get: (t<'a>, int) => option<'a>
 }
 
-@ocaml.doc(" Converting from/to normal arrays involves making a copy. ")
+@res.doc(" Converting from/to normal arrays involves making a copy. ")
 let fromArray: array<'a> => t<'a>
 
 let toArray: t<'a> => array<'a>
 
-@ocaml.doc(" Subset of the Belt.Array oprerations that do not mutate the array. ")
+@res.doc(" Subset of the Belt.Array oprerations that do not mutate the array. ")
 let length: t<'a> => int
 
 let size: t<'a> => int

diff --git a/tests/analysis_tests/tests-reanalyze/deadcode/src/ImportJsValue.res b/tests/analysis_tests/tests-reanalyze/deadcode/src/ImportJsValue.res
@@ -1,4 +1,4 @@
-@ocaml.doc("
+@res.doc("
   * Wrap JS values to be used from Reason
   ")
 @genType.import("./MyMath")

diff --git a/tests/analysis_tests/tests-reanalyze/deadcode/src/ImportMyBanner.res b/tests/analysis_tests/tests-reanalyze/deadcode/src/ImportMyBanner.res
@@ -1,4 +1,4 @@
-@ocaml.doc("
+@res.doc("
   * Wrap component MyBanner to be used from Reason.
   ")
 @genType

diff --git a/tests/analysis_tests/tests/src/Completion.res b/tests/analysis_tests/tests/src/Completion.res
@@ -7,7 +7,7 @@ module MyList = List
 //        ^com
 
 module Dep: {
-  @ocaml.doc("Some doc comment") @deprecated("Use customDouble instead")
+  @res.doc("Some doc comment") @deprecated("Use customDouble instead")
   let customDouble: int => int
 } = {
   let customDouble = foo => foo * 2

diff --git a/tests/analysis_tests/tests/src/DocComments.res b/tests/analysis_tests/tests/src/DocComments.res
@@ -1,4 +1,4 @@
-@ns.doc("  Doc comment with a triple-backquote example
+@res.doc("  Doc comment with a triple-backquote example
 
   ```res example
     let a = 10
@@ -24,7 +24,7 @@ let docComment2 = 12
 //    ^hov
 
 
-@ns.doc("  Doc comment with a triple-backquote example
+@res.doc("  Doc comment with a triple-backquote example
 
   ```res example
     let a = 10

diff --git a/tests/analysis_tests/tests/src/DocumentSymbol.res b/tests/analysis_tests/tests/src/DocumentSymbol.res
@@ -1,7 +1,7 @@
 module MyList = Belt.List
 
 module Dep: {
-  @ocaml.doc("Some doc comment") @deprecated("Use customDouble instead")
+  @res.doc("Some doc comment") @deprecated("Use customDouble instead")
   let customDouble: int => int
 } = {
   let customDouble = foo => foo * 2

diff --git a/tests/analysis_tests/tests/src/Hover.res b/tests/analysis_tests/tests/src/Hover.res
@@ -9,9 +9,9 @@ module Id = {
   type x = int
 }
 
-@ocaml.doc("This module is commented")
+@res.doc("This module is commented")
 module Dep: {
-  @ocaml.doc("Some doc comment")
+  @res.doc("Some doc comment")
   let customDouble: int => int
 } = {
   let customDouble = foo => foo * 2
@@ -30,7 +30,7 @@ module HoverInsideModuleWithComponent = {
   let make = () => React.null
 }
 
-@ocaml.doc("Doc comment for functionWithTypeAnnotation")
+@res.doc("Doc comment for functionWithTypeAnnotation")
 let functionWithTypeAnnotation: unit => int = () => 1
 //  ^hov
 
@@ -281,3 +281,13 @@ module Arr = Belt.Array
 
 type aliased = variant
 //    ^hov
+
+// Only @res.doc, which doc comments parse to, is a doc comment
+@res.doc("Shown on hover") let resDoc = 1
+//                              ^hov
+
+@ns.doc("Not shown on hover") let nsDoc = 1
+//                                ^hov
+
+@ocaml.doc("Not shown on hover") let ocamlDoc = 1
+//                                   ^hov
diff --git a/tests/analysis_tests/tests/src/expected/Hover.res.txt b/tests/analysis_tests/tests/src/expected/Hover.res.txt
@@ -544,3 +544,17 @@ Hover src/Hover.res 281:6
   }
 }
 
+Hover src/Hover.res 285:32
+{
+  "contents": {
+    "kind": "markdown",
+    "value": "```rescript\nint\n```\n---\nShown on hover"
+  }
+}
+
+Hover src/Hover.res 288:34
+{ "contents": { "kind": "markdown", "value": "```rescript\nint\n```" } }
+
+Hover src/Hover.res 291:37
+{ "contents": { "kind": "markdown", "value": "```rescript\nint\n```" } }
+
diff --git a/tests/gentype_tests/typescript-react-example/src/ImmutableArray.resi b/tests/gentype_tests/typescript-react-example/src/ImmutableArray.resi
@@ -1,17 +1,17 @@
-@ocaml.doc(" Immutable arrays are covariant. ")
+/** Immutable arrays are covariant. */
 type t<+'a>
 
-@ocaml.doc(" Redefine the [_] syntax, and disable the assignment [_] = _. ")
+/** Redefine the [_] syntax, and disable the assignment [_] = _. */
 module Array: {
   let get: (t<'a>, int) => option<'a>
 }
 
-@ocaml.doc(" Converting from/to normal arrays involves making a copy. ")
+/** Converting from/to normal arrays involves making a copy. */
 let fromArray: array<'a> => t<'a>
 
 let toArray: t<'a> => array<'a>
 
-@ocaml.doc(" Subset of the Belt.Array oprerations that do not mutate the array. ")
+/** Subset of the Belt.Array oprerations that do not mutate the array. */
 let length: t<'a> => int
 
 let size: t<'a> => int

diff --git a/tests/gentype_tests/typescript-react-example/src/ImportJsValue.res b/tests/gentype_tests/typescript-react-example/src/ImportJsValue.res
@@ -1,6 +1,6 @@
-@ocaml.doc("
+/**
   * Wrap JS values to be used from Reason
-  ")
+  */
 @genType.import(`./MyM\x61th`)
 external /* This is the module to import from. */
 /* Name and type of the JS value to bind to. */
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		- Editor hover, completion and `rescript-tools doc` read doc comments only from `/** */` comments (`@res.doc`); the legacy `@ocaml.doc` and `@ns.doc` attributes are no longer shown. Replace them with doc comments.