dotnet / dotnet/fsharp

XML Documentation generator is not aligned with its specification

Open
#12,650 0 comments 0 reactions 0 assignees View on GitHub
Area-XmlDocs Bug Impact-Low
Dominant language
F#
Stars
4.3k
Forks
876
Avg merge
4d 11h
Merged PRs (30d)
131

Description

_This issue has been moved from [a ticket on Developer Community](https://developercommunity.visualstudio.com/t/XML-Documentation-generator-is-not-align/1610749)._

---
[severity:It bothers me. A fix would be nice]
Hello,
I have created an example showing the XML documentation generator is not aligned with its specifications.
The name attribute generated for my example function is
`name="M:XMLDocWhiteSpaceAndRank.Test.foo(System.Int32[0:, 0:])"`
1) This function has whitespace in its XML Doc name attribute, in contradiction with the specs defined here: https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/ although this is for C#, I haven't find the matching information on this corresponding page for F# : https://docs.microsoft.com/en-us/dotnet/fsharp/language-reference/xml-documentation but unless mistaken, I expect it to be the same criterias for F#. I guess the fix should be to remove the extraneous space in the generated name attribute and keep the specs as is.
2) More over, in the spec on the web page, for arrays, the "number of commas" generated is expected to be "rank-1" (which should be 3-1=2 in my case). However, the number of commas generated is 1 (I guess the editor wrote "number of commas" but meant "number of elements separated by commas").

Please adjust the specs or the behaviour of the XML Generator.

Here is my example :

```
namespace XMLDocWhiteSpaceAndRank

module Test =

/// The XML doc name attribute generated for this function is
/// name="M:XMLDocWhiteSpaceAndRank.Test.foo(System.Int32[0:, 0:])"
let foo (array:int[,,]) =
let x:int[,,] = Array3D.zeroCreate 1 1 1
printfn "%d" x.Rank
```
I uploaded the generated XML documentation file.

---
### Original Comments

#### Feedback Bot on 12/12/2021, 11:28 PM:

We have directed your feedback to the appropriate engineering team for further evaluation. The team will review the feedback and notify you about the next steps.

---
### Original Solutions
(no solutions)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.