Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: push per-audit docs further into codebase #325

Open
woodruffw opened this issue Dec 17, 2024 · 1 comment
Open

docs: push per-audit docs further into codebase #325

woodruffw opened this issue Dec 17, 2024 · 1 comment
Labels
documentation Improvements or additions to documentation enhancement New feature or request

Comments

@woodruffw
Copy link
Owner

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 woodruffw added documentation Improvements or additions to documentation enhancement New feature or request labels Dec 17, 2024
@woodruffw
Copy link
Owner Author

  • 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).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

1 participant