docs: push per-audit docs further into codebase

[woodruffw]

Right now we have a lot of duplicated information between each <audit>.rs and its corresponding section in audits.md. We also have information that isn't shared but should be, such as long-form descriptions in audits.md that should be also included in the codebase so that SARIF and other output formats can include them.

A rough sketch for improving this:

• Move most audit docs to docstrings
• Extract those docstrings with something like the documented crate
• Dump those docstrings and embed them into audits.md via snippets

[woodruffw]

• Extract those docstrings with something like the documented crate

Messed around with this a bit and unfortunately it isn't a great fit -- the Documented trait adds an associated constant, meaning that it prevents object safety (which we need, since we turn everything into a dyn Audit or similar).

[Holzhaus]

Hi, i actually started writing my own linter before I found your crate. What I did was to use my own proc-macro crate to extract docstrings. It's not that hard, maybe you can reuse some parts.

Here is a policy function (similar to an audit in zizmor) with a docstring that is annotated with the #[policy] attribute: https://github.com/Holzhaus/ghastly/blob/main/ghastly/src/policies/expressions.rs#L16-L62

The implementation of that attribute will extract the doc comment of the function, and also register the policy using the inventory crate (you might not need the latter, but actually I find it kind of handy): https://github.com/Holzhaus/ghastly/blob/ced6bb15715c5997963042cf6f69c21074f6c559/ghastly-macros/src/lib.rs#L37-L56