TEXT\*
Display multiple lines of text in a code-like font (similar to the HTML \ element).
*LANGUAGE* is the language this code block is for. For example, if *LANGUAGE* is **C#**, then *TEXT* will get syntax highlighting for the C# language within the Mono Documentation Browser.
*SOURCE* is only interpreted by [**mdoc-update**(1)](/mdoc-update/1.md). If the *src* attribute is present when [**mdoc-update**(1)](/mdoc-update/1.md) is run, then *SOURCE* is a file (relative to [**mdoc-update**(1)](/mdoc-update/1.md)'s **--out** directory) that should be inserted as the value for *TEXT*. The contents of *TEXT* will be ignored by [**mdoc-update**(1)](/mdoc-update/1.md) and replaced on every invocation. *SOURCE* can also contain an "anchor", e.g. *src="path/to/file.cs#RegionMarker"*. If an anchor is present, *and* *LANGUAGE* is *C#*, then *#region RegionMarker* will be searched for, and the contents between the *#region* and the following *#endregion* will be inserted as the value for *TEXT* element.
- *\XML\_TEXT\*
Indicates an example that should be displayed specially. For example:
```
An introductory paragraph.
class Example {
public static void Main ()
{
System.Console.WriteLine ("Hello, World!");
}
}
```
The *example* element can contain the following elements: *c*, *code*, *list*, *para*, and *see*.
- *\XML\_TEXT\*
Identifies an exception that can be thrown by the documented member.
*\* is a top-level element, and should be nested directly under the *\* element.
*CREF* is the exception type that is thrown, while *XML\_TEXT* contains the circumstances that would cause *CREF* to be thrown.
```
was .
```
The *exception* element can contain the following elements: *block*, *para*, *paramref*, *see*, and *typeparamref*.
- *\XML\_TEXT\*
The *\* element is an "escape hatch," for including (possibly XML) content that is not valid [**mdoc**(5)](/mdoc/5.md) content. It's the moral equivalent of [**perlpod**(1)](/perlpod/1.md) *=begin format* blocks.
*TYPE* is the mime type of *XML\_TEXT*. [**mdoc**(5)](/mdoc/5.md) processors may skip *format/\>* blocks of they use a type that isn't supported.
For example:
```
```
would cause the embedded HTML *\* element to be inserted inline into the resulting HTML document when [**mdoc-export-html**(1)](/mdoc-export-html/1.md) processes the file. (Likewise, it may be skipped if processed by another program.)
*format/\>* is intended to simplify importing documentation from existing documentation sources. It should not be relied upon, if at all possible.
- *\XML\*
Create a list or table of items. *\* makes use of nested *\XML\*, *\XML\*, *\XML\_TEXT\*, and *\XML\_TEXT\* elements.
*Lists* have the syntax:
```
- Bullet 1
- Bullet 2
- Bullet 3
```
*Tables* have the syntax:
```
Column 1
Column 2
Column 3
-
Item 1-A
Item 1-B
Item 1-C
-
Item 2-A
Item 2-B
Item 2-C
```
The *item* and *description* elements can each contain text and the following elements: *block*, *c*, *para*, *paramref*, *see*, *sup*, and *typeparamref*.
- *\XML\_TEXT\*
Insert a paragraph of *XML\_TEXT*. For example,
```
This is a paragraph of text.
```
The *para* element can contain the following elements: *block*, *c*, *example*, *link*, *list*, *onequarter*, *paramref*, *see*, *sub*, *sup*, *typeparamref*, and *ul*.
- *\XML\_TEXT\*
*\* is a top-level element, and should be nested directly under the *\* element.
Describes the parameter *NAME* of the current constructor, method, or property:
```
A containing the number
of widgets to process.
```
The *param* element can contain the following elements: *block*, *c*, *example*, *para*, *paramref*, *see*, and *typeparamref*.
- *\*
Indicates that *NAME* is a parameter.
This usually renders *NAME* as italic text, so it is frequently (ab)used as an equivalent to the HTML \ element. See the *\* documentation (above) for an example.
- *\XML\_TEXT\*
Documents the security accessibility requirements of the current member.
*\* is a top-level element, and should be nested directly under the *\* element.
*CREF* is a type reference to the security permission required, while *XML\_TEXT* is a description of why the permission is required.
```
Requires permission for reading and writing files. See
,
.
```
The *permission* element can contain the following elements: *block*, *para*, *paramref*, *see*, and *typeparamref*.
- *\XML\_TEXT\*
Contains detailed information about a member.
*\* is a top-level element, and should be nested directly under the *\* element.
```
Insert detailed information here.
```
The *remarks* element can contain the following elements: *block*, *c*, *code*, *example*, *list*, *para*, *paramref*, *see*, and *typeparamref*.
- *\XML\_TEXT\*
*\* is a top-level element, and should be nested directly under the *\* element.
Describes the return value of a method:
```
A specifying whether
or not the process can access
.
```
The *returns* element can contain the following elements: *c*, *format*, *list*, *para*, *paramref*, *see*, and *typeparamref*.
- *\*, *\*
Creates a link to the specified member within the current text:
```
```
or specifies that *LANGWORD* is a language keyword:
```
```
- *\*
Do not use *seealso*, use *altmember*.
- *\*
*\* is a top-level element, and should be nested directly under the *\* element.
Permits specification of which version introduced the specified type or member.
```
```
This generally isn't required, as the *//AssemblyInfo/AssemblyVersion* elements track which assembly versions contain type or member.
- *\XML\_TEXT\*
*\* is a top-level element, and should be nested directly under the *\* element.
Provides a (brief!) overview about a type or type member.
This is usually displayed as part of a class declaration, and should be a reasonably short description of the type/member. Use *\* for more detailed information.
The *summary* element can contain the following elements: *block*, *list*, *para*, *paramref*, *see*, and *typeparamref*.
- *\XML\_TEXT\*
*\* is a top-level element, and should be nested directly under the *\* element.
This is used to document a type parameter for a generic type or generic method.
*NAME* is the name of the type parameter, while *XML\_TEXT* contains a description of the parameter (what it's used for, what restrictions it must meet, etc.).
```
The type of the underlying collection
```
The *typeparam* element can contain the following elements: *block*, *c*, *para*, *paramref*, *see*, and *typeparamref*.
- *\*
Used to indicate that *NAME* is a type parameter.
- *\XML\_TEXT\*
*\* is a top-level element, and should be nested directly under the *\* element.
Allows a property to be described.
```
A containing a widget name.
```
The *value* element can contain the following elements: *block*, *c*, *example*, *list*, *para*, *paramref*, *see*, and *typeparamref*.
## CREF FORMAT
String IDs (*CREF*s) are used to refer to a type or member of a type. String IDs are documented in ECMA-334 3rd Edition, Annex E.3.1. They consist of a *member type prefix*, the full type name (namespace + name, separated by *.*), possibly followed by the member name and other information.
Member type prefixes:
- *C:*
The CREF refers to a constructor. The (optional) parameter list is enclosed in parenthesis and follows the type name: *C:System.String(System.Char,System.Int32)*.
- *E:*
The CREF refers to an event. The event name follows the type name: *E:System.AppDomain.AssemblyLoad*.
- *F:*
The CREF refers to a field. The field name follows the type name: *F:System.Runtime.InteropServices.DllImportAttribute.SetLastError*.
- *M:*
Refers to a constructor or method. Constructors may append *.ctor* to the type name (instead of using the above *C:* constructor format), while methods append the method name and an (optional) count of the number of generic parameters. Both constructors and methods may append the method parameter list enclosed in parenthesis.
Examples: *M:System.Object..ctor*, *M:System.String..ctor(System.Char\[\])*, *M:System.String.Concat(System.Object)*, *M:System.Array.Sort\`\`1(\`\`0\[\])*, *M:System.Collections.Generic.List\`1..ctor*, *M:System.Collections.Generic.List\`1.Add(\`0)*.
- *N:*
Refers to a namespace, e.g. *N:System*.
- *P:*
Refers to a property. If the property is an indexer or takes parameters, the parameter types are appended to the property name and enclosed with parenthesis: *P:System.String.Length*, *P:System.String.Chars(System.Int32)*.
- *T:*
The CREF refers to a type, with the number of generic types appended: *T:System.String*, *T:System.Collections.Generic.List\`1*, *T:System.Collections.Generic.List\`1.Enumerator*.
To make matters more interesting, generic types & members have two representations: the "unbound" representation (shown in examples above), in which class names have the count of generic parameters appended to their name. There is also a "bound" representation, in which the binding of generic parameters is listed within '{' and '}' or '\<' and '\>'. (Use of '\<' and '\>' is less common, as within an XML document their escaped character entities must instead be used, leading to '<' and '>'.)
**Unbound:**
- **\***
*T:System.Collections.Generic.List\`1*
- **\***
*T:System.Collections.Generic.Dictionary\`2*
**Bound:**
- **\***
*T:System.Collections.Generic.List{System.Int32}*
- **\***
*T:System.Collections.Generic.List\*
- **\***
*T:System.Collections.Generic.List<System.Int32>*
- **\***
*T:System.Predicate{System.Action{System.String}}*
As you can see, bound variants can be arbitrarily complex (just like generics).
Furthermore, if a generic parameter is bound to the generic parameter of a type or method, the "index" of the type/method's generic parameter is used as the binding, so given
```
class FooType {
public static void Foo (System.Predicate predicate)
{
}
}
```
The CREF for this method is *M:FooType.Foo\`\`1(System.Predicate{\`\`0})*, *\`\`0* is the 0th generic parameter index which is bound to *System.Predicate\*.
## SEE ALSO
[mdoc(1)](/mdoc/1.md), [monodocer(1)](/monodocer/1.md)
## MAILING LISTS
- Visit http://lists.ximian.com/mailman/listinfo/mono-docs-list for details.
## WEB SITE
Visit http://www.mono-project.com for details