A standard XML documentation element for the default value of a property

[verelpode]

Thousands of pages exist in Microsoft and third-party documentation that say the default value of a property, for example...

• XmlWriterSettings.IndentChars says "The default is two spaces."
• XmlWriterSettings.Indent says "The default is false."
• and thousands of others.

The default value is very useful info that I read/lookup frequently, often at least once every workday for different properties. Considering how useful it is, I suggest formalizing it by defining a new standard XML documentation element for it, for example like this:

<defaultvalue>two spaces</defaultvalue>

Obviously the advantage of having it in an XML element is that it's machine-readable, unlike when we just write "The default value is two spaces". For example, when it in an <defaultvalue> element, then it automates the translation to languages other than English. Visual Studio could also display the default value in a prominent or standard location or style, etc. VS IntelliSense could also recognize it. Likewise, the program that converts this documentation to HTML webpages could read the new <defaultvalue> element and automatically create nice HTML for it.

The default value of a property is such a common and useful kind of info that I think it'd great to formalize it with a <defaultvalue> element.

If you wish, you could optionally take the idea one step further by defining two variations of the default value element:

• <defaultvaluedesc> could mean a description of the default value such as <defaultvaluedesc>two spaces</defaultvaluedesc> whereas....
• <defaultvalue> could mean the compiler verifies the syntax of the value, and verifies that type of value matches the type of property. For example, if a property returns a boolean value, then the compiler would accept <defaultvalue>false</defaultvalue> or true but not <defaultvalue>some text</defaultvalue>.

I'm not suggesting that all preexisting pages be updated to use a new <defaultvalue> element, rather I just mean it'd be great to use it for all future new documentation, for everyone -- for my own documentation, for Microsoft's documentation, and for documentation from other people and organizations.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 7d5aa865-b9d2-e977-a272-3886aa0a1111
• Version Independent ID: 353b1c44-b90a-e5cc-a193-7b42ec714290
• Content: Recommended tags for documentation comments - C# programming guide
• Content Source: docs/csharp/programming-guide/xmldoc/recommended-tags-for-documentation-comments.md
• Product: dotnet-csharp
• Technology: csharp-fundamentals
• GitHub Login: @BillWagner
• Microsoft Alias: wiwagn

[BillWagner]

ping @jcouv @333fred

Should I move this to the roslyn repo, or the csharplang repo for further discussion?

[sharwell]

I believe this would be best as a discussion in dotnet/csharplang. It's similar to requests like #1764.