Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Backport System.Linq API docs to source #51140

Closed
wants to merge 6 commits into from
Closed

Backport System.Linq API docs to source #51140

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
4921277
first pass backlog of System.Linq api docs
eiriktsarpalis Apr 12, 2021
7da403e
first pass of manual changes to the docs
eiriktsarpalis Apr 16, 2021
183432c
apply more custom transformations
eiriktsarpalis Apr 16, 2021
fdb8418
add missing documentation from #47231.
eiriktsarpalis Apr 21, 2021
ee80740
Fix truncated note elements
eiriktsarpalis Apr 26, 2021
99dd060
fix malformated xml
eiriktsarpalis Apr 26, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions src/libraries/Common/src/System/Collections/Generic/LargeArrayBuilder.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
namespace System.Collections.Generic
{
/// <summary>
/// Represents a position within a <see cref="System.Collections.Generic.LargeArrayBuilder{T}"/>.
/// Represents a position within a <see cref="LargeArrayBuilder{T}"/>.
/// </summary>
[DebuggerDisplay("{DebuggerDisplay,nq}")]
internal readonly struct CopyPosition
Expand All @@ -26,7 +26,7 @@ internal CopyPosition(int row, int column)
}

/// <summary>
/// Represents a position at the start of a <see cref="System.Collections.Generic.LargeArrayBuilder{T}"/>.
/// Represents a position at the start of a <see cref="LargeArrayBuilder{T}"/>.
/// </summary>
public static CopyPosition Start => default(CopyPosition);

Expand Down
2,331 changes: 1,454 additions & 877 deletions src/libraries/System.Linq.Expressions/src/System/Linq/Expressions/BinaryExpression.cs
View file
Open in desktop

Large diffs are not rendered by default.

144 changes: 65 additions & 79 deletions src/libraries/System.Linq.Expressions/src/System/Linq/Expressions/BlockExpression.cs
View file
Open in desktop

Large diffs are not rendered by default.

106 changes: 43 additions & 63 deletions src/libraries/System.Linq.Expressions/src/System/Linq/Expressions/CatchBlock.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,8 @@

namespace System.Linq.Expressions
{
/// <summary>
/// Represents a catch statement in a try block.
/// This must have the same return type (i.e., the type of <see cref="Body"/>) as the try block it is associated with.
/// </summary>
/// <summary>Represents a catch statement in a try block.</summary>
/// <remarks>The <see cref="O:System.Linq.Expressions.Expression.Catch" /> methods can be used to create a <see cref="System.Linq.Expressions.CatchBlock" />.</remarks>
[DebuggerTypeProxy(typeof(Expression.CatchBlockProxy))]
public sealed class CatchBlock
{
Expand All @@ -21,44 +19,34 @@ internal CatchBlock(Type test, ParameterExpression? variable, Expression body, E
Filter = filter;
}

/// <summary>
/// Gets a reference to the <see cref="Exception"/> object caught by this handler.
/// </summary>
/// <summary>Gets a reference to the <see cref="System.Exception" /> object caught by this handler.</summary>
/// <value>The <see cref="System.Linq.Expressions.ParameterExpression" /> object representing a reference to the <see cref="System.Exception" /> object caught by this handler.</value>
public ParameterExpression? Variable { get; }

/// <summary>
/// Gets the type of <see cref="Exception"/> this handler catches.
/// </summary>
/// <summary>Gets the type of <see cref="System.Exception" /> this handler catches.</summary>
/// <value>The <see cref="System.Type" /> object representing the type of <see cref="System.Exception" /> this handler catches.</value>
public Type Test { get; }

/// <summary>
/// Gets the body of the catch block.
/// </summary>
/// <summary>Gets the body of the catch block.</summary>
/// <value>The <see cref="System.Linq.Expressions.Expression" /> object representing the catch body.</value>
public Expression Body { get; }

/// <summary>
/// Gets the body of the <see cref="CatchBlock"/>'s filter.
/// </summary>
/// <summary>Gets the body of the <see cref="System.Linq.Expressions.CatchBlock" /> filter.</summary>
/// <value>The <see cref="System.Linq.Expressions.Expression" /> object representing the body of the <see cref="System.Linq.Expressions.CatchBlock" /> filter.</value>
public Expression? Filter { get; }

/// <summary>
/// Returns a <see cref="string"/> that represents the current <see cref="object"/>.
/// </summary>
/// <returns>A <see cref="string"/> that represents the current <see cref="object"/>.</returns>
/// <summary>Returns a <see cref="string" /> that represents the current <see cref="object" />.</summary>
/// <returns>A <see cref="string" /> that represents the current <see cref="object" />.</returns>
public override string ToString()
{
return ExpressionStringBuilder.CatchBlockToString(this);
}

/// <summary>
/// Creates a new expression that is like this one, but using the
/// supplied children. If all of the children are the same, it will
/// return this expression.
/// </summary>
/// <param name="variable">The <see cref="Variable"/> property of the result.</param>
/// <param name="filter">The <see cref="Filter"/> property of the result.</param>
/// <param name="body">The <see cref="Body"/> property of the result.</param>
/// <returns>This expression if no children changed, or an expression with the updated children.</returns>
/// <summary>Creates a new expression that is like this one, but using the supplied children. If all of the children are the same, it will return this expression.</summary>
/// <param name="variable">The <see cref="System.Linq.Expressions.CatchBlock.Variable" /> property of the result.</param>
/// <param name="filter">The <see cref="System.Linq.Expressions.CatchBlock.Filter" /> property of the result.</param>
/// <param name="body">The <see cref="System.Linq.Expressions.CatchBlock.Body" /> property of the result.</param>
/// <returns>This expression if no children are changed or an expression with the updated children.</returns>
public CatchBlock Update(ParameterExpression? variable, Expression? filter, Expression body)
{
if (variable == Variable && filter == Filter && body == Body)
Expand All @@ -69,69 +57,61 @@ public CatchBlock Update(ParameterExpression? variable, Expression? filter, Expr
}
}

/// <summary>Provides the base class from which the classes that represent expression tree nodes are derived. It also contains <see langword="static" /> (<see langword="Shared" /> in Visual Basic) factory methods to create the various node types. This is an <see langword="abstract" /> class.</summary>
/// <remarks></remarks>
/// <example>The following code example shows how to create a block expression. The block expression consists of two <see cref="System.Linq.Expressions.MethodCallExpression" /> objects and one <see cref="System.Linq.Expressions.ConstantExpression" /> object.
/// :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/cs/program.cs" id="Snippet13":::
/// :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet13":::</example>
public partial class Expression
{
/// <summary>
/// Creates a <see cref="CatchBlock"/> representing a catch statement.
/// The <see cref="Type"/> of object to be caught can be specified but no reference to the object
/// will be available for use in the <see cref="CatchBlock"/>.
/// </summary>
/// <param name="type">The <see cref="Type"/> of <see cref="Exception"/> this <see cref="CatchBlock"/> will handle.</param>
/// <summary>Creates a <see cref="System.Linq.Expressions.CatchBlock" /> representing a catch statement.</summary>
/// <param name="type">The <see cref="System.Linq.Expressions.Expression.Type" /> of <see cref="System.Exception" /> this <see cref="System.Linq.Expressions.CatchBlock" /> will handle.</param>
/// <param name="body">The body of the catch statement.</param>
/// <returns>The created <see cref="CatchBlock"/>.</returns>
/// <returns>The created <see cref="System.Linq.Expressions.CatchBlock" />.</returns>
/// <remarks>The <see cref="O:System.Linq.Expressions.Expression.Type" /> of <see cref="System.Exception" /> to be caught can be specified but no reference to the <see cref="System.Exception" /> object will be available for use in the <see cref="System.Linq.Expressions.CatchBlock" />.</remarks>
public static CatchBlock Catch(Type type, Expression body)
{
return MakeCatchBlock(type, null, body, filter: null);
}

/// <summary>
/// Creates a <see cref="CatchBlock"/> representing a catch statement with a reference to the caught object for use in the handler body.
/// </summary>
/// <param name="variable">A <see cref="ParameterExpression"/> representing a reference to the <see cref="Exception"/> object caught by this handler.</param>
/// <summary>Creates a <see cref="System.Linq.Expressions.CatchBlock" /> representing a catch statement with a reference to the caught <see cref="System.Exception" /> object for use in the handler body.</summary>
/// <param name="variable">A <see cref="System.Linq.Expressions.ParameterExpression" /> representing a reference to the <see cref="System.Exception" /> object caught by this handler.</param>
/// <param name="body">The body of the catch statement.</param>
/// <returns>The created <see cref="CatchBlock"/>.</returns>
/// <returns>The created <see cref="System.Linq.Expressions.CatchBlock" />.</returns>
public static CatchBlock Catch(ParameterExpression variable, Expression body)
{
ContractUtils.RequiresNotNull(variable, nameof(variable));
return MakeCatchBlock(variable.Type, variable, body, filter: null);
}

/// <summary>
/// Creates a <see cref="CatchBlock"/> representing a catch statement with
/// an <see cref="Exception"/> filter but no reference to the caught <see cref="Exception"/> object.
/// </summary>
/// <param name="type">The <see cref="Type"/> of <see cref="Exception"/> this <see cref="CatchBlock"/> will handle.</param>
/// <summary>Creates a <see cref="System.Linq.Expressions.CatchBlock" /> representing a catch statement with an <see cref="System.Exception" /> filter but no reference to the caught <see cref="System.Exception" /> object.</summary>
/// <param name="type">The <see cref="System.Linq.Expressions.Expression.Type" /> of <see cref="System.Exception" /> this <see cref="System.Linq.Expressions.CatchBlock" /> will handle.</param>
/// <param name="body">The body of the catch statement.</param>
/// <param name="filter">The body of the <see cref="Exception"/> filter.</param>
/// <returns>The created <see cref="CatchBlock"/>.</returns>
/// <param name="filter">The body of the <see cref="System.Exception" /> filter.</param>
/// <returns>The created <see cref="System.Linq.Expressions.CatchBlock" />.</returns>
public static CatchBlock Catch(Type type, Expression body, Expression? filter)
{
return MakeCatchBlock(type, null, body, filter);
}

/// <summary>
/// Creates a <see cref="CatchBlock"/> representing a catch statement with
/// an <see cref="Exception"/> filter and a reference to the caught <see cref="Exception"/> object.
/// </summary>
/// <param name="variable">A <see cref="ParameterExpression"/> representing a reference to the <see cref="Exception"/> object caught by this handler.</param>
/// <summary>Creates a <see cref="System.Linq.Expressions.CatchBlock" /> representing a catch statement with an <see cref="System.Exception" /> filter and a reference to the caught <see cref="System.Exception" /> object.</summary>
/// <param name="variable">A <see cref="System.Linq.Expressions.ParameterExpression" /> representing a reference to the <see cref="System.Exception" /> object caught by this handler.</param>
/// <param name="body">The body of the catch statement.</param>
/// <param name="filter">The body of the <see cref="Exception"/> filter.</param>
/// <returns>The created <see cref="CatchBlock"/>.</returns>
/// <param name="filter">The body of the <see cref="System.Exception" /> filter.</param>
/// <returns>The created <see cref="System.Linq.Expressions.CatchBlock" />.</returns>
public static CatchBlock Catch(ParameterExpression variable, Expression body, Expression? filter)
{
ContractUtils.RequiresNotNull(variable, nameof(variable));
return MakeCatchBlock(variable.Type, variable, body, filter);
}

/// <summary>
/// Creates a <see cref="CatchBlock"/> representing a catch statement with the specified elements.
/// </summary>
/// <param name="type">The <see cref="Type"/> of <see cref="Exception"/> this <see cref="CatchBlock"/> will handle.</param>
/// <param name="variable">A <see cref="ParameterExpression"/> representing a reference to the <see cref="Exception"/> object caught by this handler.</param>
/// <summary>Creates a <see cref="System.Linq.Expressions.CatchBlock" /> representing a catch statement with the specified elements.</summary>
/// <param name="type">The <see cref="System.Linq.Expressions.Expression.Type" /> of <see cref="System.Exception" /> this <see cref="System.Linq.Expressions.CatchBlock" /> will handle.</param>
/// <param name="variable">A <see cref="System.Linq.Expressions.ParameterExpression" /> representing a reference to the <see cref="System.Exception" /> object caught by this handler.</param>
/// <param name="body">The body of the catch statement.</param>
/// <param name="filter">The body of the <see cref="Exception"/> filter.</param>
/// <returns>The created <see cref="CatchBlock"/>.</returns>
/// <remarks><paramref name="type"/> must be non-null and match the type of <paramref name="variable"/> (if it is supplied).</remarks>
/// <param name="filter">The body of the <see cref="System.Exception" /> filter.</param>
/// <returns>The created <see cref="System.Linq.Expressions.CatchBlock" />.</returns>
/// <remarks><paramref name="type" /> must be non-null and match the type of <paramref name="variable" /> (if it is supplied).</remarks>
public static CatchBlock MakeCatchBlock(Type type, ParameterExpression? variable, Expression body, Expression? filter)
{
ContractUtils.RequiresNotNull(type, nameof(type));
Expand Down
Loading