dotnet / SqlClient

Microsoft.Data.SqlClient provides database connectivity to SQL Server for .NET applications.
MIT License
857 stars 286 forks source link

XML Documentation Fix - Batch #2 #2834

Closed benrr101 closed 2 months ago

benrr101 commented 2 months ago

Description: This PR is the first of several that aim to fix https://github.com/dotnet/SqlClient/issues/2013. As per discussion on that issue, this PR removes Markdown style comments and replaces them with XML style comments.

This batch also takes into consideration the comments from the previous PR, so hopefully there will be less corrections required on this PR.

One open question - the cref format requires using a prefix for the type of the thing being reference (eg, M: for method, T: for types). However, it's unclear how the reference should be done for overloads, either specifying all overloads or specifying a single overload. The sandcastle docs say O: can be used to refer to all overloads (https://ewsoftware.github.io/XMLCommentsGuide/html/983fed56-321c-4daf-af16-e3169b28ffcd.htm#Examples)? The markdown docs use %2A (*) in cref's quite a bit, which I think effectively refers to all overloads, and those should be replaced with O: prefix? Please let me know any thoughts on this

JRahnama commented 2 months ago

on the built M.D.SqlClient.xml in artifacts\Project\bin\Windows_NT\Release.AnyCPU\Microsoft.Data.SqlClient\netcore\net6.0 folder I see

 <member name="M:Microsoft.Data.SqlClient.SqlBulkCopyColumnMapping.#ctor(System.String,System.String)">
            <!-- No matching elements were found for the following include tag --><include file="../../../../../../doc/snippets/Microsoft.Data.SqlClient/SqlBulkCopyColumnMapping.xml" path="docs/members[@name=&quot;SqlBulkCopyColumnMapping&quot;]/ctor[@name=&quot;sourceColumnStringAnddestinationColumnString&quot;]/*" />
        </member>
benrr101 commented 2 months ago

@JRahnama thanks for pointing that out. I'll add the fix for it to the next PR.

codecov[bot] commented 2 months ago

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 72.02%. Comparing base (d89372a) to head (31f8cf1). Report is 15 commits behind head on main.

Additional details and impacted files ```diff @@ Coverage Diff @@ ## main #2834 +/- ## ========================================== - Coverage 72.02% 72.02% -0.01% ========================================== Files 299 299 Lines 61430 61436 +6 ========================================== + Hits 44246 44249 +3 - Misses 17184 17187 +3 ``` | [Flag](https://app.codecov.io/gh/dotnet/SqlClient/pull/2834/flags?src=pr&el=flags&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=dotnet) | Coverage Δ | | |---|---|---| | [addons](https://app.codecov.io/gh/dotnet/SqlClient/pull/2834/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=dotnet) | `92.90% <ø> (ø)` | | | [netcore](https://app.codecov.io/gh/dotnet/SqlClient/pull/2834/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=dotnet) | `75.93% <ø> (-0.03%)` | :arrow_down: | | [netfx](https://app.codecov.io/gh/dotnet/SqlClient/pull/2834/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=dotnet) | `70.25% <ø> (+0.04%)` | :arrow_up: | Flags with carried forward coverage won't be shown. [Click here](https://docs.codecov.io/docs/carryforward-flags?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=dotnet#carryforward-flags-in-the-pull-request-comment) to find out more.

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

benrr101 commented 2 months ago

@JRahnama sorry I though I already merged this one. I'll cherry pick the fixes from the next pr back into this one!