docs: mention the Assert APIs, add misc fixes

[rami3l]

Closes #4358.

I still feel more comfortable putting such internal-facing documentation in the code directly, but probably we can add a pointer to the doc comments or rustdoc ¹ in the dev guide?

Footnotes

1. I believe publishing API docs on GitHub pages is useful even if the project itself is an application. What do you think? ↩

[Copilot]

Pull Request Overview

Adds comprehensive documentation for the Assert helper type in clitools.rs, including usage patterns, snapshot testing workflow, and redaction details.

• Introduce detailed doc comments on Assert struct
• Update constructor doc link to reference only SanitizedOutput

[rami3l]

@djc Thanks for the quick review! When reading the guides however I have noticed a few existing problems, so I wish to fix them here as well. I hope you feel okay with this 🙏

[rami3l]

@djc @ChrisDenton Wait, there might be something going on with our Windows CI... This PR in itself should be innocent.

[ChrisDenton]

Seems like a problem in aws_lc_sys:

= note: libaws_lc_sys-3fe107a3c1c4f7cf.rlib(mem.obj) : warning LNK4099: PDB '' was not found with 'libaws_lc_sys-3fe107a3c1c4f7cf.rlib(mem.obj)' or at ''; linking object as if no debug info␍
          LINK : error LNK1218: warning treated as error; no output file generated␍

The empty name for the pdb file looks like a bug. We could work around it by ignoring it. E.g. add /IGNORE:1218 to the command line options. An alternative is to simply remove the /WX linker option and thus ignore all warnings.

[rami3l]

@ChrisDenton It wasn't there an hour ago, it's weird. I'll send an issue to aws-lc-rs, and could you have a look at the workaround(s) available? Many thanks in advance 🙇

[ChrisDenton]

Strange. Was there a nightly toolchain update or anything like that?

I can implement a workaround but it might be a little while until I'm at a machine.

[rami3l]

Strange. Was there a nightly toolchain update or anything like that?

@ChrisDenton I've checked both aws-lc-rs and Runner Images and confirmed that no one would like to cut a new release towards the weekend, of course. OTOH I highly suspect that the direct cause of this issue is some sort of cache invalidation 🤦‍♀️

[rami3l]

@ChrisDenton It turned out to be a build cache-related issue! You can have a rest for now as a reset has just been performed, and hopefully things will get back on track real soon 🙏