Skip to content

Property Value

Jump to bottom
Laura Verdoes edited this page Nov 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 typeWordingExamples
Class, interface, or structureA/An/The <description, without specifying the data type>. The default is default 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 is null.
Flag enumA 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 is None.

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 of NotifyFilters.LastWrite, NotifyFilters.FileName, and NotifyFilters.DirectoryName.
Other enumOne 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 is BorderStyle.FixedSingle.
Booleantrue 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 is true.

Type: System.Boolean
true if the stream supports writing; false if the stream is closed or was opened with read-only access. The default is true.

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.
ArrayAn array that contains XXX.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.

Home

Clone this wiki locally