- Notifications
You must be signed in to change notification settings - Fork1.6k
Property Value
Laura Verdoes edited this pageNov 3, 2021 ·3 revisions
The Property Value section describes the value of a property. Add the property value description to the <value> tag.
- Provide a clear description of the property value. Keep the description concise, but provide enough context.
- Use wording that is programming language-neutral.
- If the property type is an enum member, briefly specify what the enum defines. The wording should distinguish between single enum values and flag enums, as shown in the following table.
- If the property type is an array, indicate what the array contains.
- If there is a default value that the user should be aware of, describe it in a second sentence.
- Include measurement units (for example, "in bytes" or "in pixels") if applicable.
- Don't include a link to the property value type in your descriptions. The build tools include this link automatically.
- Do not bury important information about the property value in Remarks. Include it in the description, but point to Remarks for a lengthier discussion if necessary.
The following table shows the boilerplate wording for property value descriptions. The wording varies according to the property type.
| Property type | Wording | Examples |
|---|---|---|
| Class, interface, or structure | A/An/The <description, without specifying the data type>. The default isdefault value. Note: If the abstraction is not clear from the context, you can use the wording "An object that identifies/specifies/contains...". However, avoid this unless there is no other way to describe the property value. | Type:System.Windows.Forms.Cursor The current default cursor. Type:System.Net.ICredentials The authentication credentials associated with this request. The default isnull. |
| Flag enum | A bitwise combination of the enumeration values that <additional information>. The default is<EnumMember>. | Type:System.AppDomainManagerInitializationOptions A bitwise combination of the enumeration values that describe the initialization action to perform. The default isNone. Example of flag enum with a combination of default values: Type:System.IO.NotifyFilters A bitwise combination of the enumeration values that specify the changes. The default is the bitwise OR combination ofNotifyFilters.LastWrite,NotifyFilters.FileName, andNotifyFilters.DirectoryName. |
| Other enum | One of the enumeration values that <additional information>. The default is<EnumMember>. | Type:System.Windows.Forms.BorderStyle One of the enumeration values that specifies the border style for a control. The default isBorderStyle.FixedSingle. |
| Boolean | true if XXX; otherwise,false. The default is XXX. true if XXX;false if XXX. The default is XXX. <true/false> in all cases. Note: Use the "otherwise" wording unless the second condition must be noted explicitly. Note: The wording for Boolean property values is "true if...," not "true to...." (The wording "true to...." is for parameters.) | Type:System.Boolean true if rows can be deleted from the grid; otherwise,false. The default istrue. Type:System.Boolean true if the stream supports writing;false if the stream is closed or was opened with read-only access. The default istrue. Type:System.Boolean false in all cases. |
| Other primitive or string | <Noun phrase description, without specifying the data type.> The default is XXX. | Type:System.Int32 The width, in pixels, of the columns in the grid. The default is 75. |
| Array | An array that containsXXX. | Type:System.Attribute() An array that contains the attributes of this member. Type:System.Byte() An array that contains the originator of the key pair. |