rust-tss-esapi
rust-tss-esapi copied to clipboard
parallaxsecond
Add examples in documentation
At the moment our documentation is purely comment-based and should be enhanced with some working examples of how to use the functionality within.
Here a little example to get a random byte:
#[macro_use]
extern crate log;
use tss_esapi::Context;
use tss_esapi::Tcti;
fn main() {
//let env = Env::default().filter_or("LOG_LEVEL", "warn")
env_logger::init();
let tpm_ctx_result = unsafe { Context::new(Tcti::Tabrmd) };
if tpm_ctx_result.is_err() {
error!("Connection to TPM not established: {}", tpm_ctx_result.unwrap_err());
return;
}
let mut tpm_ctx = tpm_ctx_result.unwrap();
let random = tpm_ctx.get_random(1);
if random.is_err() {
error!("Testing TPM, not able to get_random: {}", random.unwrap_err());
return;
}
info!("Testing TPM, by get_random a byte: {}", random.unwrap()[0]);
}
Hi @genofire !
Thanks for the snippet 😃 Would you like to submit a PR that adds this example?
I think for examples it is fine not to have logging and unwrap errors directly, it might simplify your snippet, if you agree.
It will take some time (days), for me it is more importent to work with Quote (and as first step with PCR) - but i could do it ... where should it be ? in README or somewhere else?
A good place to put it would be in the code documentation of the get_random function, here. That way it will show in our docs.rs documentation!
Below the # Errors section you can add an # Example section as explained here. You will probably need to put the no_run attribute on that block to only compile the example whe ntests are executed.
cargo test --doc should try to compile the example to check if it works 😃
We should target putting docs on all public items + example on main methods.
There are still methods to be documented, but I feel like examples are not always needed. I'm curious if we could just make sure there's one test doing each operation "how we expect it to be used", and somehow link to it from the docs. Otherwise we end up with very verbose documentation
I have no problem with having the examples together with the context methods. But it would be so nice if it would be possible to move them out in to separate like example files somehow.
Like this:
/// Bal bla bla
/// # Details
/// bla bla bla bla bla bla
/// # Arguments
/// bla - bla
/// bla2 - bla
/// # Examples
/// Encrypt bla:
/// include_example_from_file!("encrypt_example")
/// Decrypt bla:
/// include_example_from_file!("decrypt_example")
Would be nice to see how to implement nv operations as the old library did
Yeah, I kinda like that approach, we're not limited by the same things as in Rustdocs.
Anyone can give example for implementing rsa_encrypt() function. It should be very helpful.
Anyone can give example for implementing rsa_encrypt() function. It should be very helpful.
https://github.com/parallaxsecond/rust-tss-esapi/blob/main/tss-esapi/examples/rsa_oaep.rs
