Skip to content

Parameters

Jump to bottom
Maira Wenzel edited this page Apr 24, 2019 · 2 revisions

The Parameters section lists and describes each parameter in the declaration.

Guidelines

docs.microsoft.com displays a Parameters section automatically if it's required.

  • Include an accurate description of what should be passed for the parameter. When you write this description, think about how the parameter is used by the method.
  • Don't include a link to the parameter type, because that's added by the build, but you can specify the type in plain text (for example, "a string" for a System.String object). This reference should be programming language-neutral.
  • Keep the description concise, but provide enough context to make it meaningful. Don't just repeat the parameter name. For example, a length parameter for an operation that sets the length of a stream could be described like this: "The desired length of the current stream, in bytes." Avoid meaningless descriptions like this: "The length."
  • Include important information such as which enumeration values are supported, whether the value can be null, the unit of measurement, if applicable, and the default value, if one exists. For example: the bufferSize parameter for the System.IO.Stream.CopyTo (Stream, Int32) method has the following description:

    bufferSize
    Type: System.Int32
    The size of the buffer, in bytes. This value must be greater than zero. The default size is 4096.
  • Do not bury important information about the parameter in Remarks. Include it in the parameter description, but point to Remarks for a lengthier discussion if necessary.

How-To

docs.microsoft.com automatically populates the Parameter column of the Parameters table with the name of each parameter, and applies the correct style. However, be sure to apply the parameterReference tag to other occurrences of parameter names throughout the documentation.

The guidelines for writing parameter descriptions depend on the kind of type or member that you are documenting, as well as on the type of the parameter itself. Write a description of each parameter, using the wording shown in the tables in the following sections. The sections and tables are organized by topic type.

For the phrasing to use for type parameters, see the Type Parameters Subsection.

Home

Clone this wiki locally