The generated .NET API reference maps every type to learn.microsoft.com, including types Microsoft does not document. Those links 404, and resq-software/docs publishes them.
Surfaced by the weekly link checker in resq-software/docs (run 31911555547), which had been broken since May and only just started reporting again.
Dead links
| Emitted URL |
Status |
Should be |
learn.microsoft.com/en-us/dotnet/api/polly.resiliencepipeline-1 |
404 |
https://www.pollydocs.org/api/Polly.ResiliencePipeline-1.html (verified 200) |
learn.microsoft.com/en-us/dotnet/api/resq.clients.coordinationhceclient |
404 |
relative link to our own generated page |
Affected pages: ResQ.Clients.BaseServiceClient.BuildResiliencePipeline(bool), ResQ.Storage.PinataClient.BuildResiliencePipeline(), ResQ.Simulation.ScenarioRunner.ctor, ResQ.Simulation.VirtualDrone.VirtualDrone(...).
Two distinct generator bugs:
- Third-party types (
Polly.*) are assumed to live on MS Learn. They need a per-namespace URL mapping, or no link at all.
- Our own types (
ResQ.Clients.*) are also sent to MS Learn instead of being cross-linked to the sibling generated page.
Also: prose URLs get linkified
ResQ.Storage.PinataOptions.ApiUrl / .GatewayUrl doc comments read Default is "https://api.pinata.cloud". These are API endpoints, not web pages — api.pinata.cloud/ returns 404 and gateway.pinata.cloud/ipfs returns 401, both correct behavior. Wrapping them in a <c> element in the XML doc comment renders them as code rather than links.
Why this needs fixing here, not downstream
resq-software/docs#124 patches the generated Markdown directly, which turns CI green now but will regress. The docs sync step recursively clears the target directory before copying the freshly generated output over it, so every hand edit under sdks/dotnet/api/ is discarded on the next api-docs run from this repo. The durable fix is the generator (and the two XML doc comments).
Filed while triaging the docs link checker. Happy to send a PR if you point me at the generator config.
The generated .NET API reference maps every type to
learn.microsoft.com, including types Microsoft does not document. Those links 404, andresq-software/docspublishes them.Surfaced by the weekly link checker in
resq-software/docs(run 31911555547), which had been broken since May and only just started reporting again.Dead links
learn.microsoft.com/en-us/dotnet/api/polly.resiliencepipeline-1https://www.pollydocs.org/api/Polly.ResiliencePipeline-1.html(verified 200)learn.microsoft.com/en-us/dotnet/api/resq.clients.coordinationhceclientAffected pages:
ResQ.Clients.BaseServiceClient.BuildResiliencePipeline(bool),ResQ.Storage.PinataClient.BuildResiliencePipeline(),ResQ.Simulation.ScenarioRunner.ctor,ResQ.Simulation.VirtualDrone.VirtualDrone(...).Two distinct generator bugs:
Polly.*) are assumed to live on MS Learn. They need a per-namespace URL mapping, or no link at all.ResQ.Clients.*) are also sent to MS Learn instead of being cross-linked to the sibling generated page.Also: prose URLs get linkified
ResQ.Storage.PinataOptions.ApiUrl/.GatewayUrldoc comments readDefault is "https://api.pinata.cloud". These are API endpoints, not web pages —api.pinata.cloud/returns 404 andgateway.pinata.cloud/ipfsreturns 401, both correct behavior. Wrapping them in a<c>element in the XML doc comment renders them as code rather than links.Why this needs fixing here, not downstream
resq-software/docs#124 patches the generated Markdown directly, which turns CI green now but will regress. The docs sync step recursively clears the target directory before copying the freshly generated output over it, so every hand edit under
sdks/dotnet/api/is discarded on the nextapi-docsrun from this repo. The durable fix is the generator (and the two XML doc comments).Filed while triaging the docs link checker. Happy to send a PR if you point me at the generator config.