[Repo Assist] Include type constraints in generated API documentation by github-actions[bot] · Pull Request #1045 · fsprojects/FSharp.Formatting

github-actions · 2026-02-26T19:01:43Z

🤖 This PR was created by Repo Assist, an automated AI assistant.

Closes #591

Root Cause

Type constraints on generic parameters (e.g. 'T : equality, 'T : comparison, 'T :> IComparable) were not extracted or displayed in generated API docs. The FSharpGenericParameter.Constraints property from FCS was available but unused — there was even a commented-out reference to indexedConstraints at SymbolReader.fs:285.

Fix

TypeFormatter.fs: Added formatConstraintAsText and formatConstraintsAsText using FSharpGenericParameter.Constraints from FCS. Handles: equality, comparison, struct, not struct, default constructor, unmanaged, coercion (:>), enum, delegate, and member constraints.
ApiDocTypes.fs: Added constraints: string list field to ApiDocMemberDetails; added Constraints member and FormatTypeConstraints to ApiDocMember.
SymbolReader.fs: Compute constraints from the same tps list used for type parameters; pass empty list for union cases, fields, and static params.
GenerateHtml.fs: Display a Constraints: line after Type parameters: in the member tooltip. Also fixed a pre-existing issue where type parameters were only shown when modifiers were non-empty.

Example

For val hash : 'T -> int when 'T : equality, the generated docs will now show:

Type parameters: 'T
Constraints: 'T : equality

Trade-offs

The ApiDocMemberDetails discriminated union gained a new constraints field — this is a minor breaking change for any external code that pattern-matches on it (same category of change as any field addition to this DU).
Member constraints (SRTP, e.g. (member Foo : 'T -> int)) are formatted using FSharpDisplayContext.Empty which may include fully-qualified type names in some cases.

Test Status

Build: ✅ succeeded
Tests: ✅ 72/72 passed, 4 skipped (pre-existing)
Formatting: ✅ Fantomas applied

Generated by Repo Assist for issue #591

To install this agentic workflow, run
gh aw add githubnext/agentics/workflows/repo-assist.md@afb00b92a9514fee9a14c583f059a03d05738f70

Fixes #591. Type constraints on generic parameters (e.g. 'T : equality, 'T : comparison, 'T :> IComparable) are now extracted from FCS symbols and displayed in the member tooltip in the 'Constraints:' line. Changes: - TypeFormatter.fs: add formatConstraintAsText and formatConstraintsAsText using FSharpGenericParameter.Constraints from FCS; supports equality, comparison, struct, reference-type, default-ctor, unmanaged, coercesTo, enum, delegate, and member constraints - ApiDocTypes.fs: add 'constraints: string list' field to ApiDocMemberDetails; add Constraints member and FormatTypeConstraints to ApiDocMember - SymbolReader.fs: compute constraints from generic type parameters and pass to ApiDocMemberDetails; empty list for union cases, fields, static params - GenerateHtml.fs: display 'Constraints:' line after 'Type parameters:'; also fix: type parameters now show independently of modifiers Co-authored-by: Copilot <[email protected]>

src/FSharp.Formatting.ApiDocs/TypeFormatter.fs

nojaf · 2026-02-27T07:51:41Z

/repo-assist revisit PR to address analyzer remarks.

…r.fs Address GRA-INTERPOLATED-001 analyzer warnings by adding %s type specifiers to all 19 interpolated holes in formatConstraintAsText. Co-authored-by: Copilot <[email protected]>

github-actions · 2026-02-27T07:58:18Z

Commit pushed: 1586689

Generated by Repo Assist

…dce2011594bb32d

dsyme · 2026-02-27T11:53:07Z

/repo-assist I'd like this feature to be opt in please, via a documented project setting. This is because the inferred type constraints can be long and verbose and often unhelpful as they might overwhelm.

Also please make sure all the project settings that we have available are all documented, may as well do that in this PR too

…all project settings - Add FsDocsShowTypeConstraints MSBuild property (default: false) - Thread through ProjectCracker → BuildCommand → ApiDocInput → SymbolReader - Gate formatConstraintsAsText behind ctx.ShowTypeConstraints - Add ShowTypeConstraints: bool to ApiDocInput and ReadingContext - Expand docs/commandline.md with comprehensive project settings table - Update RELEASE_NOTES.md to describe the opt-in flag Co-authored-by: Copilot <[email protected]>

github-actions · 2026-02-27T12:04:45Z

Commit pushed: 7101a8f

Generated by Repo Assist

dsyme · 2026-02-27T17:33:47Z

/repo-assist I'd like you to study the "shortConstraints" option in the F# compiler. I want you to make this "Short" form the default behaviour for fsdocs, with the project file setting having values None, Short and Full. Full should be pretty much as you have it.

https://github.com/dotnet/fsharp/blob/main/src/Compiler/Checking/NicePrint.fs#L799

Also add systematic tests for everything you've added and update the docs

…hort/Full) - Replace ShowTypeConstraints: bool with TypeConstraintDisplayMode DU - Short (default): shows constraints inline as 'when' clause - Full: shows separate 'Constraints:' section - None: hides constraints entirely - Update MSBuild property from FsDocsShowTypeConstraints to FsDocsTypeConstraints - Update GenerateMarkdown.fs to also render constraints - Add TypeConstraintTests module to FsLib2 test library - Add 10 systematic NUnit tests covering all modes - Update docs/commandline.md and RELEASE_NOTES.md Co-authored-by: Copilot <[email protected]>

github-actions · 2026-02-27T17:59:14Z

Commit pushed: bd301a2

Generated by Repo Assist

src/FSharp.Formatting.ApiDocs/GenerateHtml.fs

src/FSharp.Formatting.ApiDocs/GenerateMarkdown.fs

src/FSharp.Formatting.ApiDocs/ApiDocTypes.fs

+/// Controls how type constraints on generic members are displayed in generated API docs.
+[<RequireQualifiedAccess>]
+type TypeConstraintDisplayMode =
+    /// Do not display type constraints.
+    | None
+    /// Display constraints inline as a 'when' clause appended to the type parameters (default).
+    | Short
+    /// Display constraints in a separate 'Constraints:' section in the member tooltip.
+    | Full


dsyme · 2026-02-27T18:06:23Z

/repo-assist Fix the code scanning code review alerts

…matic constraint tests - Short mode now renders constraints as 'T (requires equality) matching the F# compiler's shortConstraints=true DisplayEnv format - Add FormatShortTypeConstraints property that strips the type-variable prefix from constraint strings (e.g. 'T : equality -> equality) - Add requiresCoercion, requiresStruct, requiresUnmanaged test fixtures - Add systematic model-level tests for FormatShortTypeConstraints verifying abbreviation is correct for equality, comparison, coercion, struct - Update Full mode tests to verify full-form 'T : equality text - Update docs and RELEASE_NOTES to describe (requires ...) style Co-authored-by: Copilot <[email protected]>

github-actions · 2026-02-27T18:24:52Z

Commit pushed: e7c0282

Generated by Repo Assist

github-actions · 2026-02-27T18:24:55Z

🤖 This is an automated response from Repo Assist.

I've updated the PR to implement the (requires ...) style as you requested. Here's a summary of what changed:

Changes

Short mode now uses F# compiler's `shortConstraints` style

Previously, Short mode displayed: 'T when 'T : equality

Now Short mode displays: 'T (requires equality) — matching the shortConstraints=true format in the F# compiler's NicePrint.fs (line 799), which is the style used in VS Code quick-info tooltips.

New `FormatShortTypeConstraints` property on `ApiDocMember`

Returns the compact form with the type-variable prefix stripped:

'T : equality → "equality"
'T : comparison → "comparison"
'T :> System.IComparable → ":> System.IComparable" (keeps operator, strips 'T)
'T : struct → "struct"
Multiple constraints joined with " and "

The existing FormatTypeConstraints property still returns the full form (used by Full mode and the Constraints: section).

Summary of mode behaviours

Mode	Output example
`None`	No constraint information shown
`Short` (default)	`'T (requires equality)` inline with type params
`Full`	Separate Constraints: section: `'T : equality`

Tests

Added systematic tests covering:

FormatShortTypeConstraints abbreviates correctly for equality, comparison, coercion (:>), struct
Short output file contains requires and equality/comparison keywords
Full output file still shows Constraints: label with full constraint text
None output file still has no Constraints: label
New fixtures: requiresCoercion, requiresStruct, requiresUnmanaged

All 11 constraint tests pass ✅

Generated by Repo Assist for issue #1045

To install this agentic workflow, run
gh aw add githubnext/agentics/workflows/repo-assist.md@afb00b92a9514fee9a14c583f059a03d05738f70

src/FSharp.Formatting.ApiDocs/ApiDocTypes.fs

+        else
+            let toShort (full: string) =
+                // Coercion: "'T :> Type" → ":> Type"
+                let coerceIdx = full.IndexOf(" :> ")


src/FSharp.Formatting.ApiDocs/ApiDocTypes.fs

+                    full[coerceIdx + 1 ..]
+                else
+                    // Regular constraint: "'T : equality" → "equality"
+                    let colonIdx = full.IndexOf(" : ")


src/FSharp.Formatting.ApiDocs/GenerateHtml.fs

+                                                if m.TypeConstraintDisplayMode = TypeConstraintDisplayMode.Short then
+                                                    match m.FormatShortTypeConstraints with
+                                                    | None -> encode v
+                                                    | Some c -> encode ($"{v} (requires {c})")


src/FSharp.Formatting.ApiDocs/GenerateHtml.fs

+                                                if m.TypeConstraintDisplayMode = TypeConstraintDisplayMode.Short then
+                                                    match m.FormatShortTypeConstraints with
+                                                    | None -> encode v
+                                                    | Some c -> encode ($"{v} (requires {c})")


src/FSharp.Formatting.ApiDocs/GenerateMarkdown.fs

+                      if m.TypeConstraintDisplayMode = TypeConstraintDisplayMode.Short then
+                          match m.FormatShortTypeConstraints with
+                          | None -> p [ !!("Type parameters: " + v) ]
+                          | Some c -> p [ !!($"Type parameters: {v} (requires {c})") ]


src/FSharp.Formatting.ApiDocs/GenerateMarkdown.fs

+                      if m.TypeConstraintDisplayMode = TypeConstraintDisplayMode.Short then
+                          match m.FormatShortTypeConstraints with
+                          | None -> p [ !!("Type parameters: " + v) ]
+                          | Some c -> p [ !!($"Type parameters: {v} (requires {c})") ]


github-actions · 2026-02-27T18:31:12Z

Pull request created: #1053

Generated by Repo Assist

github-actions bot added automation repo-assist labels Feb 26, 2026

github-actions bot mentioned this pull request Feb 26, 2026

Include type constraints in documentation #591

Open

ci: trigger CI checks

606b255

dsyme marked this pull request as ready for review February 26, 2026 19:03

github-advanced-security bot found potential problems Feb 26, 2026

View reviewed changes

fix: add %s format specifiers to interpolated strings in TypeFormatte…

1586689

…r.fs Address GRA-INTERPOLATED-001 analyzer warnings by adding %s type specifiers to all 19 interpolated holes in formatConstraintAsText. Co-authored-by: Copilot <[email protected]>

ci: trigger CI checks

764e0ab

This comment has been minimized.

Sign in to view

github-actions bot mentioned this pull request Feb 27, 2026

[Repo Assist] Monthly Activity 2026-02 #973

Open

12 tasks

Merge branch 'main' into repo-assist/fix-issue-591-type-constraints-9…

d4f4683

…dce2011594bb32d

ci: trigger CI checks

0456c16

This comment has been minimized.

Sign in to view

This was referenced Feb 27, 2026

[Repo Assist] Split MarkdownParser.fs into inline and block-level parsers #1052

Open

Split large files across the repository #1022

Open

ci: trigger CI checks

ff74812

github-advanced-security bot found potential problems Feb 27, 2026

View reviewed changes

ci: trigger CI checks

8aa42e2

github-advanced-security bot found potential problems Feb 27, 2026

View reviewed changes

Conversation

github-actions bot commented Feb 26, 2026

Root Cause

Fix

Example

Trade-offs

Test Status

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nojaf commented Feb 27, 2026

Uh oh!

github-actions bot commented Feb 27, 2026

Uh oh!

This comment has been minimized.

dsyme commented Feb 27, 2026

Uh oh!

github-actions bot commented Feb 27, 2026

Uh oh!

This comment has been minimized.

dsyme commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Feb 27, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Check notice

dsyme commented Feb 27, 2026

Uh oh!

github-actions bot commented Feb 27, 2026

Uh oh!

github-actions bot commented Feb 27, 2026

Changes

Short mode now uses F# compiler's shortConstraints style

New FormatShortTypeConstraints property on ApiDocMember

Summary of mode behaviours

Tests

Uh oh!

Check warning

Check warning

Check warning

Check warning

Check warning

Check warning

github-actions bot commented Feb 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

dsyme commented Feb 27, 2026 •

edited

Loading

Short mode now uses F# compiler's `shortConstraints` style

New `FormatShortTypeConstraints` property on `ApiDocMember`