I propose we add support for the <inheritdoc> and <include> XML documentation tags in F#'s XML documentation comments, aligning with C#'s capabilities. This would allow F# code to inherit and include XML doc content in a more maintainable manner, improving documentation parity with C#.
This suggestion is based on dotnet/fsharp#19175 opened by @jwosty, who noted that the F# docs explicitly mention this is not supported and that there was no issue tracking it. We are moving this idea forward here for formal language suggestion tracking.
The existing way of approaching this problem in F# is manually duplicating all XML documentation across overrides or repeated API patterns. Neither <inheritdoc> nor <include> are supported. The F# docs explicitly state this limitation: F# XML Documentation Limitations.
Pros and Cons
The advantages of making this adjustment to F# are
- Parity with C# for documentation reuse and inheritance.
- Easier to write and maintain comprehensive documentation, especially in larger codebases with many overrides or repeated API patterns.
- Improved documentation consistency across projects.
- Reduces duplication and risk of documentation drifting out of sync.
The disadvantages of making this adjustment to F# are
- Implementation introduces some compiler complexity.
- Could potentially hide places where docs should be uniquely written, if over-used.
Extra information
Estimated cost (XS, S, M, L, XL, XXL):
S (for <include>) / M (for <inheritdoc>)
Related suggestions:
Affidavit (please submit!)
Please tick these items by placing a cross in the box:
Please tick all that apply:
For Readers
If you would like to see this issue implemented, please click the : +1: emoji on this issue. These counts are used to generally order the suggestions by engagement.
I propose we add support for the
<inheritdoc>and<include>XML documentation tags in F#'s XML documentation comments, aligning with C#'s capabilities. This would allow F# code to inherit and include XML doc content in a more maintainable manner, improving documentation parity with C#.This suggestion is based on dotnet/fsharp#19175 opened by @jwosty, who noted that the F# docs explicitly mention this is not supported and that there was no issue tracking it. We are moving this idea forward here for formal language suggestion tracking.
The existing way of approaching this problem in F# is manually duplicating all XML documentation across overrides or repeated API patterns. Neither
<inheritdoc>nor<include>are supported. The F# docs explicitly state this limitation: F# XML Documentation Limitations.Pros and Cons
The advantages of making this adjustment to F# are
The disadvantages of making this adjustment to F# are
Extra information
Estimated cost (XS, S, M, L, XL, XXL):
S (for
<include>) / M (for<inheritdoc>)Related suggestions:
<inheritdoc>and<include>(#19175)<include>support: Add support for<include>XML documentation tag (#19186)<inheritdoc>does not yet have a working prototype implementation.Affidavit (please submit!)
Please tick these items by placing a cross in the box:
Please tick all that apply:
For Readers
If you would like to see this issue implemented, please click the : +1: emoji on this issue. These counts are used to generally order the suggestions by engagement.