docs(sql): p_-prefixed Oracle examples in the four stale doc comments (final-review nit)

2026-08-05 07:28:24 -04:00
parent db295c1439
commit bfdf74ec0b
4 changed files with 9 additions and 9 deletions
@@ -56,10 +56,10 @@ public interface ISqlDialect

    /// <summary>
    ///     The token that stands for a bound parameter <b>in the command text</b> — <c>"@k0"</c> for
-    ///     SqlClient/Npgsql, <c>":k0"</c> for ODP.NET — given the caller's bare base name (<c>"k0"</c>,
+    ///     SqlClient/Npgsql, <c>":p_k0"</c> for ODP.NET — given the caller's bare base name (<c>"k0"</c>,
    ///     <c>"w"</c>, <c>"schema"</c>).
    ///     <para><b>Why the marker and the bind name are two members.</b> They are the same string on every
-    ///     provider but Oracle, where the SQL text carries <c>:schema</c> while
+    ///     provider but Oracle, where the SQL text carries <c>:p_schema</c> while
    ///     <see cref="DbParameter.ParameterName"/> is the bare <c>schema</c>. Modelling one and deriving the
    ///     other means a call site guessing at a convention it does not own — the exact defect this seam
    ///     exists to prevent, and one that surfaces as a runtime bind failure (or, worse under
@@ -91,7 +91,7 @@ public interface ISqlDialect
    ///     parameters are added or it is executed. A no-op for providers that need none.
    ///     <para><b>Oracle uses this to set <c>OracleCommand.BindByName = true</c></b>, and that call is the
    ///     sharpest correctness edge on this seam: ODP.NET binds <em>by position</em> by default, so a
-    ///     multi-parameter statement (the planner's <c>IN (:k0, :k1, …)</c> list, the catalog path's
+    ///     multi-parameter statement (the planner's <c>IN (:p_k0, :p_k1, …)</c> list, the catalog path's
    ///     <c>schema</c> + <c>table</c> pair) would bind values to the wrong markers whenever the parameter
    ///     order and the marker order differ — publishing one tag's value onto another tag's node with no
    ///     error anywhere. Every command that carries parameters — the poll path, the catalog path, the
@@ -164,7 +164,7 @@ public interface ISqlDialect
    /// <summary>
    ///     Catalog query listing tables + views in one schema — the browser's schema-expand level. Carries one
    ///     parameter under the base name <c>schema</c>, spelled with this dialect's own
-    ///     <see cref="ParameterMarker"/> (<c>@schema</c> on SqlClient, <c>:schema</c> on ODP.NET); callers bind
+    ///     <see cref="ParameterMarker"/> (<c>@schema</c> on SqlClient, <c>:p_schema</c> on ODP.NET); callers bind
    ///     it under <see cref="ParameterBindName"/> of the same base name.
    /// </summary>
    string ListTablesSql { get; }
@@ -18,7 +18,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Sql;
 ///     the allow-list cannot itself be an injection vector. No identifier is quoted into text on this path.
 ///     The bind names come from <see cref="ISqlDialect.ParameterBindName"/> over those two base names, so
 ///     they can never disagree with the markers in the dialect's own catalog SQL (<c>@schema</c> on SQL
-///     Server, <c>:schema</c> on Oracle).</para>
+///     Server, <c>:p_schema</c> on Oracle).</para>
 ///     <para><b>Failures throw; they do not degrade to an empty catalog.</b> An empty catalog would reject
 ///     every tag, which is indistinguishable at the OPC UA surface from a database whose objects were all
 ///     dropped. A caller that cannot read the catalog has not learned that the tags are invalid — it has
@@ -14,13 +14,13 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Sql;
 ///     <para><b>Injection boundary (design §8.1).</b> Identifiers reach the command text through
 ///     <see cref="ISqlDialect.QuoteIdentifier"/> and nothing else; every authored value becomes a
 ///     <c>k0</c>/<c>w</c> parameter — spelled with the dialect's own <see cref="ISqlDialect.ParameterMarker"/>
-///     (<c>@k0</c> on SQL Server, <c>:k0</c> on Oracle) — with the value carried in
+///     (<c>@k0</c> on SQL Server, <c>:p_k0</c> on Oracle) — with the value carried in
 ///     <see cref="SqlQueryPlan.Parameters"/>. There is no interpolation of tag content into SQL anywhere in
 ///     this type.</para>
 ///     <para><b>The base names are this planner's, the spelling is the dialect's.</b> Each plan carries the
 ///     markers it emitted <em>and</em> the matching <see cref="ISqlDialect.ParameterBindName"/>s, so the
 ///     reader binds what the planner minted instead of re-deriving a provider convention — the two differ on
-///     ODP.NET (<c>:k0</c> in the text, bare <c>k0</c> on the parameter).</para>
+///     ODP.NET (<c>:p_k0</c> in the text, bare <c>p_k0</c> on the parameter).</para>
 /// </summary>
 public static class SqlGroupPlanner
 {
@@ -12,8 +12,8 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Sql;
 ///     <see cref="DbParameter"/> named by the positionally-aligned <see cref="ParameterBindNames"/>. There is
 ///     no path by which a tag's <c>keyValue</c> or <c>whereValue</c> reaches the command text.</para>
 ///     <para><b>Markers and bind names are carried separately</b> because they are not the same string on
-///     every provider: ODP.NET's text says <c>:k0</c> while its <see cref="DbParameter.ParameterName"/> is the
-///     bare <c>k0</c>. Both lists are positionally aligned with <see cref="Parameters"/>, so a binding site
+///     every provider: ODP.NET's text says <c>:p_k0</c> while its <see cref="DbParameter.ParameterName"/> is the
+///     bare <c>p_k0</c>. Both lists are positionally aligned with <see cref="Parameters"/>, so a binding site
 ///     copies the pairing the planner minted rather than re-deriving a provider convention it does not own.</para>
 ///     <para>Produced only by <see cref="SqlGroupPlanner.Plan"/>; consumed by the poll reader, which executes
 ///     <see cref="SqlText"/> once and slices the rows back to per-member snapshots.</para>