[ML-KEM] Overhaul Readme and Crate documentation #1270
Conversation
franziskuskiefer
left a comment
franziskuskiefer
left a comment
There was a problem hiding this comment.
lgtm
If you can de-duplicate by including the readme, even better.
libcrux-ml-kem/src/lib.rs
Outdated
| //! - `mlkem768::portable::generate_key_pair`, | ||
| //! | ||
| //! analogously for encapsulation and decapsulation." | ||
| //! This crate implements all three ML-KEM ([FIPS 203](https://csrc.nist.gov/pubs/fips/203/final)) variants 512, 768, and 1024. |
There was a problem hiding this comment.
Looks like you duplicate the readme here? Why not include the readme instead?
There was a problem hiding this comment.
Right, I forgot you could do #![doc = include_str!("../README.md")]! That would be much nicer.
One issue there is that we have the doc test here that is feature-guarded for mlkem768, which we couldn't do with the include. So e.g. cargo test --no-default-features -F mlkem512 will fail on that then.
There was a problem hiding this comment.
I'm not sure if/how you can run the tests from the readme. That never worked for me. But if it does, you could add the feature guards in there. Or keep the test in here.
There was a problem hiding this comment.
I've pushed a version that works. Unfortunately, just putting a #![cfg(feature = "mlkem768")] does not work, so I had to put a guarded code block in there. But it's not so bad, I think.
2 participants
This PR updates the Readme for ML-KEM to include more information on crate features and different APIs available.
It's essentially an updated version of the PQCP Readme.
The crate-level documentation is also updated accordingly, and
codecis added to the features included in thedocs.rsbuild.Fixes #1172
[skip changelog]