Skip to content

[FormRecognizer] Remove <inheritdoc> from documentation #12570

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

Merged
kinelski merged 6 commits into from
Jun 8, 2020
Merged

[FormRecognizer] Remove <inheritdoc> from documentation #12570

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
9d7adcc
form rec docs
kinelski Jun 5, 2020
7af4c5d
core docs
kinelski Jun 5, 2020
d28e427
address comments
kinelski Jun 8, 2020
96925f3
fix
kinelski Jun 8, 2020
3e5612c
Merge branch 'master' into fr-docs
kinelski Jun 8, 2020
89636ea
ignore
kinelski Jun 8, 2020
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
16 changes: 8 additions & 8 deletions sdk/core/Azure.Core/src/Operation{T}.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,8 +53,8 @@ public abstract class Operation<T> where T : notnull
/// <summary>
/// Periodically calls the server till the long-running operation completes.
/// </summary>
/// <param name="cancellationToken"></param>
/// <returns></returns>
/// <param name="cancellationToken">A <see cref="CancellationToken"/> used for the periodical service calls.</param>
/// <returns>The last HTTP response received from the server.</returns>
/// <remarks>
/// This method will periodically call UpdateStatusAsync till HasCompleted is true, then return the final result of the operation.
/// </remarks>
Expand All @@ -68,8 +68,8 @@ public abstract class Operation<T> where T : notnull
/// The interval can change based on information returned from the server.
/// For example, the server might communicate to the client that there is not reason to poll for status change sooner than some time.
/// </param>
/// <param name="cancellationToken"></param>
/// <returns></returns>
/// <param name="cancellationToken">A <see cref="CancellationToken"/> used for the periodical service calls.</param>
/// <returns>The last HTTP response received from the server.</returns>
/// <remarks>
/// This method will periodically call UpdateStatusAsync till HasCompleted is true, then return the final result of the operation.
/// </remarks>
Expand All @@ -78,8 +78,8 @@ public abstract class Operation<T> where T : notnull
/// <summary>
/// Calls the server to get updated status of the long-running operation.
/// </summary>
/// <param name="cancellationToken"></param>
/// <returns></returns>
/// <param name="cancellationToken">A <see cref="CancellationToken"/> used for the service call.</param>
/// <returns>The HTTP response received from the server.</returns>
/// <remarks>
/// This operation will update the value returned from GetRawResponse and might update HasCompleted, HasValue, and Value.
/// </remarks>
Expand All @@ -88,8 +88,8 @@ public abstract class Operation<T> where T : notnull
/// <summary>
/// Calls the server to get updated status of the long-running operation.
/// </summary>
/// <param name="cancellationToken"></param>
/// <returns></returns>
/// <param name="cancellationToken">A <see cref="CancellationToken"/> used for the service call.</param>
/// <returns>The HTTP response received from the server.</returns>
/// <remarks>
/// This operation will update the value returned from GetRawResponse and might update HasCompleted, HasValue, and Value.
/// </remarks>
Expand Down
74 changes: 63 additions & 11 deletions sdk/formrecognizer/Azure.AI.FormRecognizer/src/CopyModelOperation.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,10 +43,18 @@ public class CopyModelOperation : Operation<CustomFormModelInfo>

private RequestFailedException _requestFailedException;

/// <inheritdoc/>
/// <summary>
/// Gets an ID representing the operation that can be used to poll for the status
/// of the long-running operation.
/// </summary>
public override string Id { get; }

/// <inheritdoc/>
/// <summary>
/// Final result of the long-running operation.
/// </summary>
/// <remarks>
/// This property can be accessed only after the operation completes successfully (HasValue is true).
/// </remarks>
public override CustomFormModelInfo Value
{
get
Expand All @@ -60,10 +68,14 @@ public override CustomFormModelInfo Value
}
}

/// <inheritdoc/>
/// <summary>
/// Returns true if the long-running operation completed.
/// </summary>
public override bool HasCompleted => _hasCompleted;

/// <inheritdoc/>
/// <summary>
/// Returns true if the long-running operation completed successfully and has produced final result (accessible by Value property).
/// </summary>
public override bool HasValue => _value != null;

/// <summary>
Expand Down Expand Up @@ -129,31 +141,71 @@ internal CopyModelOperation(ServiceRestClient serviceClient, ClientDiagnostics d
Id = string.Join("/", substrs, substrs.Length - 3, 3);
}

/// <inheritdoc/>
/// <summary>
/// The last HTTP response received from the server.
/// </summary>
/// <remarks>
/// The last response returned from the server during the lifecycle of this instance.
/// An instance of <see cref="RecognizeCustomFormsOperation"/> sends requests to a server in UpdateStatusAsync, UpdateStatus, and other methods.
/// Responses from these requests can be accessed using GetRawResponse.
/// </remarks>
public override Response GetRawResponse() => _response;

/// <inheritdoc/>
/// <summary>
/// Periodically calls the server till the long-running operation completes.
/// </summary>
/// <param name="cancellationToken">A <see cref="CancellationToken"/> used for the periodical service calls.</param>
/// <returns>The last HTTP response received from the server.</returns>
/// <remarks>
/// This method will periodically call UpdateStatusAsync till HasCompleted is true, then return the final result of the operation.
/// </remarks>
public override ValueTask<Response<CustomFormModelInfo>> WaitForCompletionAsync(CancellationToken cancellationToken = default) =>
this.DefaultWaitForCompletionAsync(cancellationToken);

/// <inheritdoc/>
/// <summary>
/// Periodically calls the server till the long-running operation completes.
/// </summary>
/// <param name="pollingInterval">
/// The interval between status requests to the server.
/// The interval can change based on information returned from the server.
/// For example, the server might communicate to the client that there is not reason to poll for status change sooner than some time.
/// </param>
/// <param name="cancellationToken">A <see cref="CancellationToken"/> used for the periodical service calls.</param>
/// <returns>The last HTTP response received from the server.</returns>
/// <remarks>
/// This method will periodically call UpdateStatusAsync till HasCompleted is true, then return the final result of the operation.
/// </remarks>
public override ValueTask<Response<CustomFormModelInfo>> WaitForCompletionAsync(TimeSpan pollingInterval, CancellationToken cancellationToken = default) =>
this.DefaultWaitForCompletionAsync(pollingInterval, cancellationToken);

/// <inheritdoc/>
/// <summary>
/// Calls the server to get updated status of the long-running operation.
/// </summary>
/// <param name="cancellationToken">A <see cref="CancellationToken"/> used for the service call.</param>
/// <returns>The HTTP response received from the server.</returns>
/// <remarks>
/// This operation will update the value returned from GetRawResponse and might update HasCompleted, HasValue, and Value.
/// </remarks>
public override Response UpdateStatus(CancellationToken cancellationToken = default) =>
UpdateStatusAsync(false, cancellationToken).EnsureCompleted();

/// <inheritdoc/>
/// <summary>
/// Calls the server to get updated status of the long-running operation.
/// </summary>
/// <param name="cancellationToken">A <see cref="CancellationToken"/> used for the service call.</param>
/// <returns>The HTTP response received from the server.</returns>
/// <remarks>
/// This operation will update the value returned from GetRawResponse and might update HasCompleted, HasValue, and Value.
/// </remarks>
public override async ValueTask<Response> UpdateStatusAsync(CancellationToken cancellationToken = default) =>
await UpdateStatusAsync(true, cancellationToken).ConfigureAwait(false);

/// <summary>
/// Calls the server to get updated status of the long-running operation.
/// </summary>
/// <param name="async">When <c>true</c>, the method will be executed asynchronously; otherwise, it will execute synchronously.</param>
/// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
/// <returns>The HTTP response from the service.</returns>
/// <param name="cancellationToken">A <see cref="CancellationToken"/> used for the service call.</param>
/// <returns>The HTTP response received from the server.</returns>
private async ValueTask<Response> UpdateStatusAsync(bool async, CancellationToken cancellationToken)
{
if (!_hasCompleted)
Expand Down
74 changes: 63 additions & 11 deletions sdk/formrecognizer/Azure.AI.FormRecognizer/src/RecognizeContentOperation.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,10 +34,18 @@ public class RecognizeContentOperation : Operation<FormPageCollection>
/// <summary><c>true</c> if the long-running operation has completed. Otherwise, <c>false</c>.</summary>
private bool _hasCompleted;

/// <inheritdoc/>
/// <summary>
/// Gets an ID representing the operation that can be used to poll for the status
/// of the long-running operation.
/// </summary>
public override string Id { get; }

/// <inheritdoc/>
/// <summary>
/// Final result of the long-running operation.
/// </summary>
/// <remarks>
/// This property can be accessed only after the operation completes successfully (HasValue is true).
/// </remarks>
public override FormPageCollection Value
{
get
Expand All @@ -51,10 +59,14 @@ public override FormPageCollection Value
}
}

/// <inheritdoc/>
/// <summary>
/// Returns true if the long-running operation completed.
/// </summary>
public override bool HasCompleted => _hasCompleted;

/// <inheritdoc/>
/// <summary>
/// Returns true if the long-running operation completed successfully and has produced final result (accessible by Value property).
/// </summary>
public override bool HasValue => _value != null;

/// <summary>
Expand Down Expand Up @@ -87,31 +99,71 @@ internal RecognizeContentOperation(ServiceRestClient serviceClient, ClientDiagno
Id = operationLocation.Split('/').Last();
}

/// <inheritdoc/>
/// <summary>
/// The last HTTP response received from the server.
/// </summary>
/// <remarks>
/// The last response returned from the server during the lifecycle of this instance.
/// An instance of <see cref="RecognizeContentOperation"/> sends requests to a server in UpdateStatusAsync, UpdateStatus, and other methods.
/// Responses from these requests can be accessed using GetRawResponse.
/// </remarks>
public override Response GetRawResponse() => _response;

/// <inheritdoc/>
/// <summary>
/// Periodically calls the server till the long-running operation completes.
/// </summary>
/// <param name="cancellationToken">A <see cref="CancellationToken"/> used for the periodical service calls.</param>
/// <returns>The last HTTP response received from the server.</returns>
/// <remarks>
/// This method will periodically call UpdateStatusAsync till HasCompleted is true, then return the final result of the operation.
/// </remarks>
public override ValueTask<Response<FormPageCollection>> WaitForCompletionAsync(CancellationToken cancellationToken = default) =>
this.DefaultWaitForCompletionAsync(cancellationToken);

/// <inheritdoc/>
/// <summary>
/// Periodically calls the server till the long-running operation completes.
/// </summary>
/// <param name="pollingInterval">
/// The interval between status requests to the server.
/// The interval can change based on information returned from the server.
/// For example, the server might communicate to the client that there is not reason to poll for status change sooner than some time.
/// </param>
/// <param name="cancellationToken">A <see cref="CancellationToken"/> used for the periodical service calls.</param>
/// <returns>The last HTTP response received from the server.</returns>
/// <remarks>
/// This method will periodically call UpdateStatusAsync till HasCompleted is true, then return the final result of the operation.
/// </remarks>
public override ValueTask<Response<FormPageCollection>> WaitForCompletionAsync(TimeSpan pollingInterval, CancellationToken cancellationToken = default) =>
this.DefaultWaitForCompletionAsync(pollingInterval, cancellationToken);

/// <inheritdoc/>
/// <summary>
/// Calls the server to get updated status of the long-running operation.
/// </summary>
/// <param name="cancellationToken">A <see cref="CancellationToken"/> used for the service call.</param>
/// <returns>The HTTP response received from the server.</returns>
/// <remarks>
/// This operation will update the value returned from GetRawResponse and might update HasCompleted, HasValue, and Value.
/// </remarks>
public override Response UpdateStatus(CancellationToken cancellationToken = default) =>
UpdateStatusAsync(false, cancellationToken).EnsureCompleted();

/// <inheritdoc/>
/// <summary>
/// Calls the server to get updated status of the long-running operation.
/// </summary>
/// <param name="cancellationToken">A <see cref="CancellationToken"/> used for the service call.</param>
/// <returns>The HTTP response received from the server.</returns>
/// <remarks>
/// This operation will update the value returned from GetRawResponse and might update HasCompleted, HasValue, and Value.
/// </remarks>
public override async ValueTask<Response> UpdateStatusAsync(CancellationToken cancellationToken = default) =>
await UpdateStatusAsync(true, cancellationToken).ConfigureAwait(false);

/// <summary>
/// Calls the server to get updated status of the long-running operation.
/// </summary>
/// <param name="async">When <c>true</c>, the method will be executed asynchronously; otherwise, it will execute synchronously.</param>
/// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
/// <returns>The HTTP response from the service.</returns>
/// <param name="cancellationToken">A <see cref="CancellationToken"/> used for the service call.</param>
/// <returns>The HTTP response received from the server.</returns>
private async ValueTask<Response> UpdateStatusAsync(bool async, CancellationToken cancellationToken)
{
if (!_hasCompleted)
Expand Down
Loading