dotnet / dotnet/fsharp

Prohibit XML documentation with params for the primary constructor above the type

Open
#13,922 0 comments 2 reactions 0 assignees View on GitHub
Area-XmlDocs Feature Request
Dominant language
F#
Stars
4.3k
Forks
876
Avg merge
4d 22h
Merged PRs (30d)
144

Description

Currently, for primary constructors, you can specify XML documentation with parameters in two ways

```F#
/// A
/// x
type A(x) = ...
```

```F#
type A
/// A
/// x
(x) = ...
```

Consider some of the pros and cons of the first approach.

Pros:

- Consistency with documentation for functions: since the primary constructor is also a kind of function, it is logical to be able to specify documentation for it as for function

Cons:

- When generating a documentation file during compilation, the documentation specified in this way is generated only for the type (and therefore is not available in parameter info in C#)
- Also, it doesn't work even in F# tooltips

![image](https://user-images.githubusercontent.com/26364714/190991529-578e0eee-5237-4c74-8181-a2b66e3fceda.png)

- Constructor parameters are displayed in the type tooltip (especially unpleasant when the type has constructors in addition to the primary one); here the separation of documentation for the type and constructor occurs not at the syntax level, but at the level of thoughts of a programmer, who writes common documentation block for the type and primary constructor

![image](https://user-images.githubusercontent.com/26364714/190992515-f55904aa-13cb-4841-92ed-50599a957c32.png)

- If the constructor has documentation in two places at once
```F#
/// A
/// x
type A
/// x
(x) = ...
```
then there is no any warning

So, I propose to discuss whether it is possible to prohibit writing documentation for the primary constructor above the type, or such behavior should be allowed, but it is necessary to fix XML-doc parameters analyzer and the documentation generator.
In any case, I can help with the implementation.

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.