<?xml version="1.0" encoding="utf-8"?>
<!--
This file stores the global-used doc comments. You can use the XPath syntax to get them.
For example, you should use <include> tag to import the global doc comments:

/// <summary>
/// The test method.
/// </summary>
/// <param name="arg">
/// <include
///     file='../../global-doc-comments.xml'
///     path='g/csharp7/feature[@name="ref-returns"]/target[@name="in-parameter"]' />
/// </param>
static void F(in int arg)
{
}

Then you can reference the doc here.
-->

<g>
	<!-- Elementary docs -->
	<static-constructor>
		<summary>
			<para>
				Indicates the <see langword="static"/> constructor of the current type.
			</para>
			<para>
				This constructor will initialize some <see langword="static readonly"/> data members
				of this type that can't use a simple expression to describe the initial value.
			</para>
		</summary>
	</static-constructor>

	<!-- Developer notes -->
	<developer-notes>
		<para>
			<b>Developer Notes</b>
		</para>
	</developer-notes>

	<!-- Requires compound invocation -->
	<requires-compound-invocation>
		<para>
			<b>
				<i>
					This operator can only be used as compound one. For example:
				</i>
			</b>
			<code>
<![CDATA[
result &= expression;
result |= expression;
result ^= expression;
]]>
			</code>
		</para>
	</requires-compound-invocation>

	<!-- Large structures -->
	<large-structure>
		<b>
			<i>
				This is a large structure, which means it may cost more time to copy instance than normal structures.
				I strongly recommend you append <see langword="scoped ref readonly"/> to modify the type, as parameter or local variable modifiers,
				to tell runtime that it should be copied by its reference instead of internal value.
			</i>
		</b>
	</large-structure>

	<!-- C# features -->
	<csharp5>
		<feature name="caller-member-name">
			<target name="argument">
				<para>
					Indicates the name of the caller member to invoke this method.
				</para>
				<para>
					<i>
						The attribute <see cref="CallerMemberNameAttribute"/> allows the argument automatically
						getting the name of the caller. For example, if the property raises the event, the argument
						will pass the name of the property automatically if the argument is marked the attribute.
					</i>
				</para>
				<para>
					<i>
						For the above reason, the argument will use <see langword="null"/> as the initial value
						as the placeholder to allow the syntax valid during the compile time on one hand.
						On the other hand, you shouldn't pass any values to this argument.
					</i>
				</para>
				<para>
					<i>
						For more information, please visit
						<see href="https://docs.microsoft.com/en-us/dotnet/api/system.runtime.compilerservices.callermembernameattribute">
							The Microsoft Docs
						</see>
						for more info.
					</i>
				</para>
			</target>
		</feature>
	</csharp5>
	<csharp7>
		<feature name="deconstruction-method">
			<target name="method">
				<summary>
					Deconstruct the current instance into multiple values, which means you can use
					the value-tuple syntax to define your own deconstruction logic.
				</summary>
				<remarks>
					<para>
						For example, if you have defined a <see langword="static"/> deconstruction method <c>Deconstruct</c>
						in a <see langword="static class"/>, without any return value:
						<code>
<![CDATA[
public static void Deconstruct(out string name, out int age)
    => (name, age) = (Name, Age);
]]>
						</code>
						The following code will be legal.
						<code>
<![CDATA[
(string name, int age) = student; // Explicitly-typed variables
var (name, age) = student; // Implicitly-typed variables
]]>
						</code>
					</para>
					<para>
						Deconstruction methods also allow you using deconstruction patterns, like this:
						<code>
<![CDATA[
if (student is (name: var name, age: >= 18))
{
    Console.WriteLine(name);
}
]]>
						</code>
					</para>
				</remarks>
			</target>
		</feature>
		<feature name="custom-fixed">
			<target name="method">
				<summary>
					Returns a reference as the fixed position of the current instance.
					For example, the return value will be the pointer value that points to the zero-indexed
					place in an array.
				</summary>
				<returns>A reference as the fixed position of the current instance.</returns>
				<remarks>
					Beginning with C# 7, we can customize the return value type of a <see langword="fixed"/> variable
					if we implement a parameterless method called <c>GetPinnableReference</c>, returning by
					<see langword="ref"/> or <see langword="ref readonly"/>. For example, if we hold a fixed buffer
					of element type:
					<code>
<![CDATA[
class ExampleType
{
    private fixed short _maskList[100];

    public ref readonly short GetPinnableReference() => ref _maskList[0];
}
]]>
					</code>
					We can use <see langword="fixed"/> statement to define a variable of type <see langword="short"/>*
					as the left-value.
					<code>
<![CDATA[
var instance = new ExampleType();
fixed (short* ptr = instance)
{
    // Operation here.
}
]]>
					</code>
				</remarks>
			</target>
		</feature>
		<feature name="ref-returns">
			<target name="indexer-return">
				<i>
					This indexer returns a value by <see langword="ref"/>,
					which means you can use the return value to re-assign a new value, as the same behavior
					as the <see langword="set"/> accessor, therefore the indexer does not contain the setter.
				</i>
			</target>
			<target name="method">
				<i>
					C# 7.3 introduces a new keyword <see langword="in"/> as the parameter modifier to make the parameter
					pass by reference and be read-only. Therefore, this keyword contains 2 usages:
					<list type="number">
						<item>
							Ensure the argument to <b>be read-only</b> and cannot be modified. Otherwise,
							a new copied instance will be created to prevent any modifications on the original variable.
						</item>
						<item>
							Ensure the argument to <b>pass by reference</b> in order to treat it as the pointer or array of elements
							of this type, and treat the argument as the first element of the whole element series.
						</item>
					</list>
					From the above meaning on this keyword, we can conclude that
					we should regard it as <see langword="ref readonly"/> parameters,
					but C# requires us using the keyword <see langword="in"/> as the modifier
					on a parameter rather than <see langword="ref readonly"/>.
				</i>
			</target>
			<target name="in-parameter">
				<i>
					Please note that the parameter is an <see langword="in"/> parameter, which has the same meaning
					for <see langword="ref readonly"/> returns or locals. You can treat it as the first element
					in an array of elements. Different with <see langword="ref"/> parameter, <see langword="in"/>
					modifier has the same semantic as <see langword="ref readonly var"/>
					instead of <see langword="ref var"/>.
				</i>
			</target>
		</feature>
	</csharp7>
	<csharp9>
		<feature name="parameterless-struct-constructor">
			<target name="constructor">
				<i>
					The feature "Custom parameterless struct constructor" makes the parameterless struct constructor
					different with <c>default(T)</c>. If you has defined a parameterless struct constructor,
					<c>new T()</c> is no longer with the same meaning as <c>default(T)</c>.
				</i>
			</target>
		</feature>
		<feature name="module-initializer">
			<target name="type">
				<summary>
					<para>
						Provides with the type that contains a module initializer method, called automatically by the CLR
						(Common Language Runtime) to initialize some values.
					</para>
					<para>
						<i>
							The type is called by the compiler and the CLR (Common Language Runtime),
							which means you cannot use any members in this type manually.
						</i>
					</para>
				</summary>
			</target>
			<target name="method">
				<summary>
					Called by the runtime automatically while booting on this solution to initialize the values,
					data members or any other things that can or should be initialized here.
				</summary>
				<remarks>
					The concept <b>module</b> is different with <b>assembly</b>.
					The solution can contain multiple assemblies, while each assembly can contain multiple modules.
					However, due to the design of Visual Studio project file system, each assembly will only contain
					one module by default.
				</remarks>
			</target>
		</feature>
		<feature name="function-pointer">
			<b>
				<i>
					This member is only exposed for user for knowing the data structure backing implementation,
					so it is disallowed to invoke it.
				</i>
			</b>
		</feature>
	</csharp9>
	<csharp10>
		<feature name="caller-argument-expression">
			<para>
				<b>The value of the argument will be automatically produced by the compiler and passed into here. You may not assign this argument.</b>
			</para>
		</feature>
	</csharp10>
	<csharp11>
		<feature name="file-local">
			<target name="class" when="constant">
				<summary>
					Provides with constants and read-only values used by code in the current file.
				</summary>
			</target>
			<target name="class" when="extension">
				<summary>
					Provides with file-local extension methods.
				</summary>
			</target>
		</feature>
		<feature name="scoped-ref">
			<target name="foreach-variables">
				<para>
					<i>
						Iteration variable are implicitly <see langword="scoped"/>, which means you cannot return it outside the method
						or other members that can return.
					</i>
				</para>
			</target>
		</feature>
		<feature name="ref-fields">
			<target name="field">
				<b>
					<i>
						This field is not encapsulated into a property because C# doesn't support auto read-only properties
						returning <see langword="ref"/> or <see langword="ref readonly"/>.
					</i>
				</b>
			</target>
		</feature>
	</csharp11>
</g>