- Notifications
You must be signed in to change notification settings - Fork1.6k
Parameters: Methods and constructors
Genevieve Warren edited this pageNov 3, 2020 ·3 revisions
The following table shows the boilerplate wording for parameter descriptions within most method and constructor articles. The wording varies according to the parameter type.On<Event> methods andDispose(Boolean) methods have their own specific boilerplate wording, shown in the two topics following this one.
For general guidelines for writing parameter descriptions, seeParameters.
Note
If the type of a parameter is a primitive or string, and you want to refer to it in a generic way, use the language-neutral phrase for it.
| Parameter type | Wording | Examples |
|---|---|---|
| Class, interface, or structure | <Noun phrase description, without specifying the data type. Begin with an introductory article.> Note: If the abstraction is not clear from the context, you can use the wording "An object that identifies/specifies/containsXXX." However, avoid this unless there is no other way to describe the parameter. | p Type:System.Drawing.Point The dimensions of the control. value Type:System.Windows.Forms.IMessageFilter The message filter to remove from the message pump. credentials Type:System.Net.ICredentials The credentials associated with the authentication request. |
| Flag enum | A bitwise combination of the enumeration values <additional information, if necessary>. | options Type:System.Windows.Forms.RichTextBoxFinds A bitwise combination of the enumeration values that specifies how the search is performed. |
| Other enum | One of the enumeration values <additional information, if necessary>. Note: If some of the enumeration values are not valid, include that information in the description. | textAlign Type:System.Windows.Forms.HorizontalAlignment One of the enumeration values that specifies how text is aligned in the control. In a single-lineTextBox control, onlyHorizontalAlignment.Left is valid. |
| Boolean Note: There is special boilerplate wording for parameters ofDispose(Boolean) methods. For more information, seeParameters: Dispose(Boolean) methods. | true toXXX; otherwise,false. true toXXX;false toXXX. Note: Use the "otherwise" wording unless the second condition must be noted explicitly. Note: The wording for Boolean parameters is "true to...," not "true if...." | includePrompt Type:System.Boolean true to include prompt characters in the return string; otherwise,false. isChecking Type:System.Boolean true to indicate that the object can be frozen (without freezing it);false to actually freeze the object. |
| Other primitive or string | <Noun phrase description, without specifying the data type. Begin with an introductory article.> | width Type:System.Int32 The width of the control. fileName Type:System.String The name of an application file to run in the process. |
| Integer parameter of an indexer | The zero-based index ofXXX. | rowIndex Type:System.Int32 The zero-based index of the row that contains the value. |
| Array | An arrayXXX. | value Type:System.CodeDom.Compiler.CompilerError() An array that contains the compiler errors to add to the collection. |
| ref parameter | The <generic description of what the parameter does or represents>, passed by reference. | remoteEP Type:System.Net.EndPoint The remote server, passed by reference. |
| out parameter | When this method returns, contains a <generic description of type> that <description of what the parameter does or represents>. This parameter is treated as uninitialized. Note: If the abstraction is not clear from the context, you can use "an object" instead of <generic description of type>. However, avoid this unless there is no other way to describe the parameter. | responseStream Type:System.IO.Stream When this method returns, contains a stream that is heading back toward the transport sink. This parameter is treated as uninitialized. |