Skip to content

XML docs on client operations can't be curated; EventsClient.SubscribeAsync doesn't mention reconnect #313

Closed

Description

@Blind-Striker

What

The XML docs of client operations can't be curated. For each operation the generator writes upstream's wire description as the summary, plus generic exception lines. The curated-description channel from #300 (tools/curation.json → descriptions) targets generated model types and their members only, not client operations.

As a result, EventsClient.SubscribeAsync doesn't mention any of what #176 changed:

  • the stream reconnects on its own;
  • it never ends on its own;
  • a wrong address or a refused credential surfaces only after a minute of failing attempts;
  • a repeated EventServerConnected means events were missed.

A consumer reading only IntelliSense misses a breaking behaviour change. Today, canon (docs/architecture/client-runtime.md, Server-sent events), the guide (docs/guide/streaming.md, "A live bus that reconnects") and the CHANGELOG say it.

Found by the cross-model second review of #176's reconnect PR. It is recorded here, not fixed in that PR, because it needs a generator feature.

Possible shape

Extend the description curation so that a row can target a client operation, keyed by operation id and carrying a summary and/or remarks. Curate event.subscribe with the reconnect contract, then regenerate.

Notes

  • Generated output changes only through the generator and curation, never by hand.
  • No public API change; XML docs only.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions