`unsafe` Rust code in the kernel is required to have safety documentation. This is to ensure the correctness of `unsafe` code and is thus very important. However, at this point in time there does not exist a standard way of writing safety documentation. This leads to confusion, as authors struggle to find the right way to convey their desired intentions. Readers similarly struggle with correctly interpreting the documentation; it's the wild west. To alleviate this issue and to raise the quality of safety documentation, this patch series introduces a standard way of writing safety documentation. Because creating a standard for every possible requirement is a tall task, this series starts off very small. I hope to start more discussion, in order to find the best form of safety documentation for the kernel. Please do not hesitate to give any kind of comment. I could benefit especially from improvements to the visual look of the documentation, as this is my first time writing Sphinx documentation. For example, I am not satisfied with how the tables renders in HTML. Benno Lossin (5): doc: rust: create safety standard doc: rust: safety standard: add examples doc: rust: safety standard: add guarantees and type invariants doc: rust: safety standard: add safety requirements doc: rust: safety standard: add justifications Documentation/rust/general-information.rst | 1 + Documentation/rust/index.rst | 1 + .../rust/safety-standard/examples.rst | 70 +++++ .../rust/safety-standard/guarantee.rst | 7 + Documentation/rust/safety-standard/index.rst | 281 ++++++++++++++++++ .../rust/safety-standard/justifications.rst | 40 +++ .../rust/safety-standard/requirements.rst | 80 +++++ .../rust/safety-standard/type-invariants.rst | 18 ++ 8 files changed, 498 insertions(+) create mode 100644 Documentation/rust/safety-standard/examples.rst create mode 100644 Documentation/rust/safety-standard/guarantee.rst create mode 100644 Documentation/rust/safety-standard/index.rst create mode 100644 Documentation/rust/safety-standard/justifications.rst create mode 100644 Documentation/rust/safety-standard/requirements.rst create mode 100644 Documentation/rust/safety-standard/type-invariants.rst -- 2.45.1
