‫مستندسازی استاندارد و بدون حشو (XML Documentation) با GitHub Copilot

public async Task<OrderResponse?> GetOrderAsync(
    int orderId, 
    CancellationToken cancellationToken)

برای این متد/اینترفیس عمومی #C مستندات استاندارد و فشرده XML Documentation تولید کن.

الزامات و محورهای مستندسازی:

۱. هدف متد (Summary): کارکرد واقعی متد را بدون تکرار کلمه به کلمه نام آن شرح بده.

۲. پارامترها (): نقش، فرمت یا شرایط مورد انتظار هر پارامتر را مشخص کن.

۳. رفتار بازگشتی (): رفتار دقیق نوع بازگشتی، به‌ویژه شرایط بازگرداندن یا مجموعه‌های خالی را شفاف کن.

۴. خطاها و استثناها (): استثناهای احتمالی نظیر OperationCanceledException، ArgumentOutOfRangeException یا خطاهای دامنه را همراه با تگ مربوطه مستند کن.

۵. از توضیح جزئیات بدیهی پیاده‌سازی داخلی و ایجاد کدهای تکراری و بی‌ارزش (Boilerplate) پرهیز کن.

/// <summary>
/// Gets the order async.
/// </summary>
/// <param name="orderId">The order id.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>The order response.</returns>

/// <summary>
/// Retrieves the detailed information of an existing order by its unique identifier.
/// </summary>
/// <param name="orderId">The positive integer identifier representing the targeted order.</param>
/// <param name="cancellationToken">A token to monitor for cancellation requests during the asynchronous I/O operation.</param>
/// <returns>
/// A task representing the asynchronous operation. The task result contains the <see cref="OrderResponse"/> 
/// matching the identifier, or <see langword="null"/> if no corresponding order is found.
/// </returns>
/// <exception cref="ArgumentOutOfRangeException">Thrown when <paramref name="orderId"/> is less than or equal to zero.</exception>
/// <exception cref="OperationCanceledException">Thrown if the operation is canceled via the <paramref name="cancellationToken"/>.</exception>

/// <summary>
/// Retrieves an order by its unique identifier.
/// </summary>
/// <param name="orderId" example="1042">The unique identifier of the order.</param>
/// <param name="cancellationToken">Cancellation token.</param>
/// <response code="200">Returns the requested order data.</response>
/// <response code="404">If no order matches the provided identifier.</response>
/// <response code="400">If the provided orderId is invalid.</response>

• استفاده از تگ‌های کمکی ( و ): این تگ‌ها در IDE (مانند Visual Studio و Rider) به صورت هایپرلینک به انواع داده تبدیل می‌شوند و تجربه ناوبری (IntelliSense Navigation) بهتری فراهم می‌کنند.
• ارزیابی تطابق با رفتار واقعی: خروجی هوش مصنوعی را همیشه با منطق کد بسنجید؛ اگر متدی استثنایی پرتاب نمی‌کند یا هرگز مقدار null بازنمی‌گرداند، آن تگ را حذف کنید تا مستندات گمراه‌کننده نباشند.
• دستور اختصاصی /doc در Copilot Chat: با انتخاب امضای متد و ارسال دستور /doc concise contract-based می‌توانید بلافاصله کامنت‌های ساختاریافته دریافت کنید.