Document OdbcParameter.Offset

[roji]

Inspected the source code, and it seems like there's a pattern in ODBC where a large buffer is assigned to a parameter, and then Offset and Size are used to refer to a window within that buffer each time (see this doc page).

/cc @carlossanlop @mairaw @ajcvickers

[carlossanlop]

Looks great, @roji. Thanks for making the change. Let's wait for the build to finish without warnings, and also for a review from the @dotnet/docs team.

[carlossanlop]

Left a comment for you to consider, @roji.

[roji]

Build passed

[carlossanlop]

@roji the build had another warning (it will say it passes, but we need to look at the "warning" message in the CI).
I left a comment. Can you please address it?

[carlossanlop]

Thank you @roji. Approved.
@dotnet/docs can someone from the Docs team approve and merge this change?

[Thraka]

@carlossanlop

Sure thing. Question about it though. Are you all using a tool to import these comments? I continually see these weird indentation on the markdown remarks. I don't know why it's all indented 1 space under the heading, but it's badly formed markdown.

[roji]

I personally copy-paste other remark fragments and try to maintain whatever style/indentation is already there... we may want to do a pass over whole sections to correct this kind of thing.

[carlossanlop]

@Thraka this PR in particular was manually documented by @roji .

I do have a tool that automatically ports triple slash comments to dotnet-api-docs, and I have a few PRs out that were generated with it (any PR I have for System.Reflection.Metadata). No one else uses this tool (except for one isolated PR sent a few months ago by the WPF team, but it has been since merged).

All my other PRs I have out for review were manually documented by me, no tool involved.

Can you point out the indentation problems you're referring to? Here or in my PRs.

[Thraka]

Pretty much all of them (and I think they are generated by the tools) have a starting space on all lines under ## Remarks. To pass generic linter rules, you want empty lines between types of content (headers, lists, paragraphs, etc) and don't want lines to start with a space.

so in this example, you would have something like:

          <format type="text/markdown"><![CDATA[

## Remarks
+
- The <xref:System.Data.Odbc.OdbcParameter.Offset> property is used for binary and string types. For fixed length data types, the value of <xref:System.Data.Odbc.OdbcParameter.Offset> is ignored.
+The <xref:System.Data.Odbc.OdbcParameter.Offset> property is used for binary and string types. For fixed length data types, the value of <xref:System.Data.Odbc.OdbcParameter.Offset> is ignored.

- For nonstring data types and ANSI string data, the <xref:System.Data.Odbc.OdbcParameter.Offset> property refers to the number of bytes. For Unicode string data, <xref:System.Data.Odbc.OdbcParameter.Offset> refers to the number of characters.
+For nonstring data types and ANSI string data, the <xref:System.Data.Odbc.OdbcParameter.Offset> property refers to the number of bytes. For Unicode string data, <xref:System.Data.Odbc.OdbcParameter.Offset> refers to the number of characters.

- ]]></format>
+]]></format>