Summary
The Hybrid overloads document none of their parameters — only a <summary>. As a result boost (added in #355) has no documentation there, and neither does alpha, limit, filters, rerank, or any of the other ~17.
This is a pre-existing gap, not a regression from #355. Filing it separately so it can be fixed as what it actually is: Hybrid's parameters are undocumented, not boost is undocumented.
Current state
Of the 106 public client methods that take a Boost? boost parameter, 76 have a <param name="boost"> tag and 30 do not:
| File |
Missing |
QueryClient.Hybrid.cs |
6 of 6 |
GenerateClient.Hybrid.cs |
6 of 6 |
Typed/TypedQueryClient.Hybrid.cs |
6 of 6 |
Typed/TypedGenerateClient.Hybrid.cs |
6 of 6 |
GenerateClient.NearVector.cs |
4 of 8 |
QueryClient.NearText.cs |
2 of 6 (the static extension overloads) |
Every one of those 30 methods documents zero parameters. The ones that do document their parameters all got a boost tag in #355, so the split is clean and consistent — the gap tracks "method has no param docs at all", nothing to do with boost specifically.
For parity context: the Python client documents boost= on all 14 of its query/generate methods (weaviate/weaviate-python-client#2057), so a C# user calling Hybrid(...) currently gets less than a Python user calling hybrid().
Why #355 didn't fix it
CS1573 is all-or-nothing per method: it only fires when some parameters are documented but not all. Adding just <param name="boost"> to a Hybrid overload would trigger CS1573 for the other 17. So documenting boost there requires documenting every parameter on the method — correctly out of scope for a feature PR.
What the fix looks like
Mechanical. For each of the 30 methods, add a <param> tag per parameter, following the existing house style in QueryClient.NearVector.cs (thin one-liners — "The alpha", "The limit"). The boost line is copied verbatim from the existing text, which is already byte-identical across all 76 public uses:
/// <param name="boost">The boost for soft-ranking results. Preview: requires Weaviate 1.38+ (older servers silently ignore it)</param>
The rich prose stays on the Boost model in Models/Boost.cs — the <param> tag is only a pointer and should not duplicate it.
Roughly 500 tags across ~30 methods (Hybrid overloads carry 17–20 parameters each).
An alternative is <inheritdoc cref="..."/> on the thin delegating overloads, documenting only the canonical implementation. That cuts the volume by ~2/3, but overload crefs need full signatures (long, and brittle under refactors), and the repo only uses <inheritdoc/> in two places today and never with a cref. Probably not worth introducing as a new convention here.
Worth knowing: no compiler setting catches this
CS1573 needs partial documentation — Hybrid has none, so it stays silent.CS1591 needs a missing doc comment — Hybrid has a <summary>, so it stays silent too.
The toolchain is structurally blind to "documents zero params", which is why this survived and why it will drift back after any fix. A guard would need a custom CI check asserting every public method's parameters each have a matching <param> tag. That's arguably the more durable half of this issue.
Suggested scope
- Add the missing
<param> tags to the 30 methods above.
- (Optional, higher value) Add a CI check so it can't regress.
Summary
The
Hybridoverloads document none of their parameters — only a<summary>. As a resultboost(added in #355) has no documentation there, and neither doesalpha,limit,filters,rerank, or any of the other ~17.This is a pre-existing gap, not a regression from #355. Filing it separately so it can be fixed as what it actually is: Hybrid's parameters are undocumented, not boost is undocumented.
Current state
Of the 106 public client methods that take a
Boost? boostparameter, 76 have a<param name="boost">tag and 30 do not:QueryClient.Hybrid.csGenerateClient.Hybrid.csTyped/TypedQueryClient.Hybrid.csTyped/TypedGenerateClient.Hybrid.csGenerateClient.NearVector.csQueryClient.NearText.csEvery one of those 30 methods documents zero parameters. The ones that do document their parameters all got a
boosttag in #355, so the split is clean and consistent — the gap tracks "method has no param docs at all", nothing to do with boost specifically.For parity context: the Python client documents
boost=on all 14 of its query/generate methods (weaviate/weaviate-python-client#2057), so a C# user callingHybrid(...)currently gets less than a Python user callinghybrid().Why #355 didn't fix it
CS1573is all-or-nothing per method: it only fires when some parameters are documented but not all. Adding just<param name="boost">to a Hybrid overload would triggerCS1573for the other 17. So documentingboostthere requires documenting every parameter on the method — correctly out of scope for a feature PR.What the fix looks like
Mechanical. For each of the 30 methods, add a
<param>tag per parameter, following the existing house style inQueryClient.NearVector.cs(thin one-liners — "The alpha", "The limit"). Theboostline is copied verbatim from the existing text, which is already byte-identical across all 76 public uses:The rich prose stays on the
Boostmodel inModels/Boost.cs— the<param>tag is only a pointer and should not duplicate it.Roughly 500 tags across ~30 methods (Hybrid overloads carry 17–20 parameters each).
An alternative is
<inheritdoc cref="..."/>on the thin delegating overloads, documenting only the canonical implementation. That cuts the volume by ~2/3, but overload crefs need full signatures (long, and brittle under refactors), and the repo only uses<inheritdoc/>in two places today and never with a cref. Probably not worth introducing as a new convention here.Worth knowing: no compiler setting catches this
CS1573needs partial documentation — Hybrid has none, so it stays silent.CS1591needs a missing doc comment — Hybrid has a<summary>, so it stays silent too.The toolchain is structurally blind to "documents zero params", which is why this survived and why it will drift back after any fix. A guard would need a custom CI check asserting every public method's parameters each have a matching
<param>tag. That's arguably the more durable half of this issue.Suggested scope
<param>tags to the 30 methods above.