refactor: rename overloaded constructors to from* names [codex]

docs/content/docs/contributing/api-modelling.mdx

@@ -58,6 +58,48 @@ external addEventListenerWithCapture: (
 
 When naming an overloaded function, we can use the `With` suffix to indicate that it is an overloaded function.
 
+### Constructor overloads
+
+Constructors follow a different naming rule than methods.
+
+- Keep singleton constructors named `make`.
+- Keep true default constructors named `make`, even when the constructor family also has typed overloads.
+- When a constructor family does not have a default constructor, use `from*` names for every overload, including the first one.
+- Base `from*` names on the source input type: `fromString`, `fromArrayBuffer`, `fromMediaStream`, `fromURLWithProtocols`, and so on.
+- If an optional labeled argument hides a real default constructor, split that binding into `make()` plus typed `from*` overloads instead of keeping the optional argument on `make`.
+
+For example, these constructor families are easier to understand than numbered overloads:
+
+```ReScript
+@new
+external fromString: (~family: string, ~source: string) => fontFace = "FontFace"
+
+@new
+external fromDataView: (~family: string, ~source: DataView.t) => fontFace = "FontFace"
+
+@new
+external fromArrayBuffer: (~family: string, ~source: ArrayBuffer.t) => fontFace = "FontFace"
+```
+
+And if a constructor really does have a default form, split it instead of hiding it:
+
+```ReScript
+@new
+external make: unit => domMatrix = "DOMMatrix"
+
+@new
+external fromString: string => domMatrix = "DOMMatrix"
+
+@new
+external fromArray: array<float> => domMatrix = "DOMMatrix"
+```
+
+Single-source constructor variants should take the source value directly without a label.
+
+Keep `makeWith*` names for non-default convenience constructors that are not part of a source-type overload family.
+
+Constructor naming is currently verified with compile-coverage tests. Runtime verification for these constructor families will be added later when the Vitest and happy-dom harness lands.
+
 ### Decoded variants
 
 We can be pragmatic with overloaded functions and use model them in various creative ways.  

docs/content/docs/contributing/documentation.mdx

@@ -21,7 +21,8 @@ It keeps the user inside the IDE and avoids context switching.
 The documentation for each binding should roughly follow this structure:
 
 - signature
-- key description (tip: check MDN for inspiration)
+- short description (tip: check MDN for inspiration)
+- `Source shape:` block with links for the overload-specific input types
 - example usage
 - link to the MDN documentation
 
@@ -44,3 +45,28 @@ window->Window.fetch("https://rescript-lang.org")
 external fetch: (window, string, ~init: requestInit=?)
   => promise<response> = "fetch"
 ````
+
+Constructor overloads should use the same structure, but make the differentiating input shape explicit.
+Link ReScript stdlib types such as `string`, `array<'a>`, `ArrayBuffer.t`, and `DataView.t`, and link project-local records or aliases when the constructor takes one of those shapes.
+If a constructor variant has a single source input, show it as a direct unlabeled argument in both the signature and example.
+
+````ReScript
+/*
+`fromArray(array<float>)`
+
+The DOMMatrix() constructor creates a new DOMMatrix from an array of matrix component values.
+
+Source shape:
+- ReScript [array](https://rescript-lang.org/docs/manual/api/stdlib/array) of numeric values accepted by MDN [DOMMatrix()](https://developer.mozilla.org/docs/Web/API/DOMMatrix/DOMMatrix).
+
+```res
+let matrix = DOMMatrix.fromArray([1., 0., 0., 1., 0., 0.])
+```
+
+[Read more on MDN](https://developer.mozilla.org/docs/Web/API/DOMMatrix)
+*/
+@new
+external fromArray: array<float> => domMatrix = "DOMMatrix"
+````
+
+For now, these examples stay compile-coverage oriented. Runtime verification of constructor behavior will be handled later via Vitest and happy-dom.

packages/CSSFontLoading/src/FontFace.res

@@ -1,28 +1,70 @@
 /**
+`fromString(~family: string, ~source: string, ~descriptors: fontFaceDescriptors=?)`
+
+The FontFace() constructor creates a new FontFace object from CSS source text.
+
+Source shape:
+- `family`: ReScript [string](https://rescript-lang.org/docs/manual/primitive-types/#string) for the font family name.
+- `source`: ReScript [string](https://rescript-lang.org/docs/manual/primitive-types/#string) containing CSS [`@font-face` `src`](https://developer.mozilla.org/docs/Web/CSS/@font-face/src) text.
+- `descriptors`: local [`fontFaceDescriptors`](../#fontFaceDescriptors) values for optional constructor descriptors.
+
+```res
+let fontFace =
+  FontFace.fromString(~family="Inter", ~source="url(/fonts/inter.woff2)")
+```
+
 [Read more on MDN](https://developer.mozilla.org/docs/Web/API/FontFace)
 */
 @new
-external make: (
+external fromString: (
   ~family: string,
   ~source: string,
   ~descriptors: Types.fontFaceDescriptors=?,
 ) => Types.fontFace = "FontFace"
 
 /**
+`fromDataView(~family: string, ~source: DataView.t, ~descriptors: fontFaceDescriptors=?)`
+
+The FontFace() constructor creates a new FontFace object from DataView-backed font data.
+
+Source shape:
+- `family`: ReScript [string](https://rescript-lang.org/docs/manual/primitive-types/#string) for the font family name.
+- `source`: ReScript [`DataView.t`](https://rescript-lang.org/docs/manual/api/stdlib/dataview) mapped to MDN [DataView](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/DataView).
+- `descriptors`: local [`fontFaceDescriptors`](../#fontFaceDescriptors) values for optional constructor descriptors.
+
+```res
+let fontFace =
+  FontFace.fromDataView(~family="Inter", ~source=myDataView)
+```
+
 [Read more on MDN](https://developer.mozilla.org/docs/Web/API/FontFace)
 */
 @new
-external make2: (
+external fromDataView: (
   ~family: string,
   ~source: DataView.t,
   ~descriptors: Types.fontFaceDescriptors=?,
 ) => Types.fontFace = "FontFace"
 
 /**
+`fromArrayBuffer(~family: string, ~source: ArrayBuffer.t, ~descriptors: fontFaceDescriptors=?)`
+
+The FontFace() constructor creates a new FontFace object from ArrayBuffer-backed font data.
+
+Source shape:
+- `family`: ReScript [string](https://rescript-lang.org/docs/manual/primitive-types/#string) for the font family name.
+- `source`: ReScript [`ArrayBuffer.t`](https://rescript-lang.org/docs/manual/api/stdlib/arraybuffer) mapped to MDN [ArrayBuffer](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer).
+- `descriptors`: local [`fontFaceDescriptors`](../#fontFaceDescriptors) values for optional constructor descriptors.
+
+```res
+let fontFace =
+  FontFace.fromArrayBuffer(~family="Inter", ~source=myArrayBuffer)
+```
+
 [Read more on MDN](https://developer.mozilla.org/docs/Web/API/FontFace)
 */
 @new
-external make3: (
+external fromArrayBuffer: (
   ~family: string,
   ~source: ArrayBuffer.t,
   ~descriptors: Types.fontFaceDescriptors=?,

packages/Canvas/src/Path2D.res

@@ -1,16 +1,55 @@
 type domMatrix2DInit = WebApiDOM.Types.domMatrix2DInit
 
 /**
+`make()`
+
+The Path2D() constructor creates a new empty Path2D object.
+
+Source shape:
+- no source input; this constructor creates a fresh MDN [Path2D](https://developer.mozilla.org/docs/Web/API/Path2D).
+
+```res
+let path = Path2D.make()
+```
+
 [Read more on MDN](https://developer.mozilla.org/docs/Web/API/Path2D)
 */
 @new
-external make: (~path: Types.path2D=?) => Types.path2D = "Path2D"
+external make: unit => Types.path2D = "Path2D"
 
 /**
+`fromPath2D(path2D)`
+
+The Path2D() constructor creates a new Path2D object by copying another Path2D source.
+
+Source shape:
+- local [`Path2D.t`](#t) mapped to MDN [Path2D](https://developer.mozilla.org/docs/Web/API/Path2D).
+
+```res
+let copiedPath = Path2D.fromPath2D(existingPath)
+```
+
+[Read more on MDN](https://developer.mozilla.org/docs/Web/API/Path2D)
+*/
+@new
+external fromPath2D: Types.path2D => Types.path2D = "Path2D"
+
+/**
+`fromString(string)`
+
+The Path2D() constructor creates a new Path2D object from SVG path data text.
+
+Source shape:
+- ReScript [string](https://rescript-lang.org/docs/manual/primitive-types/#string) containing SVG path data accepted by MDN [Path2D()](https://developer.mozilla.org/docs/Web/API/Path2D/Path2D).
+
+```res
+let path = Path2D.fromString("M0 0 L10 10")
+```
+
 [Read more on MDN](https://developer.mozilla.org/docs/Web/API/Path2D)
 */
 @new
-external make2: (~path: string=?) => Types.path2D = "Path2D"
+external fromString: string => Types.path2D = "Path2D"
 
 /**
 [Read more on MDN](https://developer.mozilla.org/docs/Web/API/CanvasRenderingContext2D/closePath)