fix: improve documentation

[Dustin-Ray]

will update with specific areas to focus on ASAP.

[Dustin-Ray]

Need to update all undocumented functions and structs with documentation. This is a great first issue. Heres how it should be tackled:

1. Take a look at ops.rs. This is the most well-documented part of the library. We want the whole library to look like this. Great rust code is often more documentation than actual code.
2. Identify any functions without documentation. Find out what they do and how they are used. I'm happy to engage and answer any questions at any time!
3. Document the functions exactly how they are formatted in ops.rs. vscode has a DocTest function that will run a test on the documentation and tell you if it is acceptable, Each function documentation should have:

• All arguments labelled and defined
• Anything in self being replaced clearly notated
• Anything in self being initialized clearly notated
• Usage examples for any function that is being called
• Structs/enums should have all fields labelled. If you arent sure what something is, just ask! Here we are practicing how to reach out and collaborate when you need help. This is a crucial skill in any software engineering job.

Documentation is one of the most important components of awesome maintainable code. It helps others learn and use your project effectively, cuts down on development time, and increases developer understanding of a codebase as they write the docs.

[Dustin-Ray]

Heres an example of good documentation for a struct in capycrypt:

/// An object containing the fields necessary to represent an asymmetric keypair.
pub struct KeyPair {
    /// String indicating the owner of the key, can be arbitrary
    pub owner: String,
    /// Public encryption key
    pub pub_key: EdCurvePoint,
    /// value representing secret scalar, None if KeyType is PUBLIC
    pub priv_key: Vec<u8>,
    /// Date key was generated
    pub date_created: String,
    /// Selected curve type
    pub curve: EdCurves,
}

Heres a struct that isnt documented completely and needs help:

/// Message type for which cryptographic traits are defined.
pub struct Message {
    pub msg: Box<Vec<u8>>,
    pub sym_nonce: Option<Vec<u8>>,
    pub asym_nonce: Option<EdCurvePoint>,
    pub digest: Option<Vec<u8>>,
    pub op_result: Option<bool>,
    pub sig: Option<Signature>,
}

There are plenty of other places in this library that could use some help and this is an awesome way to learn about the library, rust, cryptography, and lots of other core concepts. We can't merge any pull requests unless they make sense and are complete! But you're super smart and awesome and won't have any issues with that :D good luck!

[Dustin-Ray]

Finally, here is an example of a fully documented function from src/ops:

    /// # Message Digest
    /// Computes SHA3-d hash of input. Does not consume input.
    /// Replaces `Message.digest` with result of operation.
    /// ## Arguments:
    /// * `d: u64`: requested security strength in bits. Supported
    /// bitstrengths are 224, 256, 384, or 512.
    /// ## Usage:
    /// ```
    /// use capycrypt::{Hashable, Message};
    /// // Hash the empty string
    /// let mut data = Message::new(&mut vec![]);
    /// // Obtained from OpenSSL
    /// let expected = "a7ffc6f8bf1ed76651c14756a061d662f580ff4de43b49fa82d80a4b80f8434a";
    /// // Compute a SHA3 digest with 256 bits of security
    /// data.compute_sha3_hash(256);
    /// assert!(hex::encode(data.digest.unwrap().to_vec()) == expected);
    /// ```
    fn compute_sha3_hash(&mut self, d: u64) {
        self.digest = match d {
            224 | 256 | 384 | 512 => Some(shake(&mut self.msg, d)),
            _ => panic!("Value must be either 224, 256, 384, or 512"),
        }
    }

Notice in particular the usage examples. These will pop up when you hover over a function and give you a working example right out of the box. In fact, when running

cargo test

to execute all of the unit tests, they will fail if the examples in your documentation do not work. VScode gives you a nice button to test the docs to make sure they pass when you write the docs this way. This is a wonderful feature of rust that leads to high-quality code that is easy to use and maintain.

[omibo]

@drcapybara I am working on this. Should I merge the commits gradually, or just pull request when the documentation is completely done?

[Dustin-Ray]

hey! thanks for all of the effort. you can open up a PR whenever you want and request to merge to main. then we can move from there 👍