I have to say, this style of commenting has always been a pet hate of mine, where the person is just restating in English what the code says fine on its own. There is also a similar style I don’t like very much, where comments get used to delineate blocks of code and they provide a sort of running commentary on what’s happening.
It looks something like this:
// Lets build this object
...
// Now lets do something with it
...
// Now lets save it in the database
...
The vast majority of the time the code is saying the same thing fine on its own. I’ve never really seen anyone give a compelling argument for this commenting style. The problem here as well is, you now have two sets of things to maintain: code and comments. It doesn’t happen very often, but sometimes, the code gets changed and the comments don’t, which leads to a very confusing situation.
I would prefer to document at the function level rather than having those comments.
Well, I don’t want to appear to dictate what should be done. That’s just a personal opinion of mine.
I do think it would be useful though for an open source project like ours if we could have all our public functions nicely documented with doc comments so that you would get nice documentation for our crates in stuff like docs.rs.
I’m not sure how you were going to go about doing this, but could you give GPT whole function definitions and ask it to produce doc comments?
OK I’ll check that after I have eaten - in the meantime here is a second attempt from ChatGPT to the original query to re keys.rs - is this better from your PoV?
API documentation:
`fn validate_sk_for_url(&self, secret_key: &SecretKey, url: &str) -> Result<String>`
* Accepts a secret key of type `SecretKey` and a string url.
* Returns a `Result<String>` where the `Ok` variant contains the XOR name of the public key derived from the provided secret key as a hex encoded string, and the `Err` variant contains an error.
* Validates the provided secret key with the URL by checking if the XOR/NRS-URL corresponds to the public key derived from the provided client id.
`fn new_keypair_with_pk_url(&self) -> Result<(Keypair, SafeUrl)>`
* Returns a `Result<(Keypair, SafeUrl)>` where the `Ok` variant contains a BLS keypair of type `Keypair` and a `SafeUrl` object, and the `Err` variant contains an error.
* Generates a new random BLS keypair along with a URL for the public key.
`fn serialize_bls_key(secret_key: &BlsSecretKey, path: impl AsRef<Path>) -> Result<()>`
* Accepts a BLS secret key of type `BlsSecretKey` and a path where the key should be serialized.
* Returns a `Result<()>` where the `Ok` variant indicates success, and the `Err` variant contains an error.
* Serializes the provided BLS secret key to hex in a file at the given path. If the path already exists it will be overwritten.
`fn deserialize_bls_key(path: impl AsRef<Path>) -> Result<BlsSecretKey>`
* Accepts a path to a file containing a serialized BLS secret key.
* Returns a `Result<BlsSecretKey>` where the `Ok` variant contains the deserialized key, and the `Err` variant contains an error.
* Deserializes a BLS secret key from a file at the given path.
Struct members:
* None
Enum variants:
* None
Method params:
* `validate_sk_for_url` takes a `secret_key` of type `SecretKey` and a `url` of type `&str`.
* `new_keypair_with_pk_url` takes no parameters.
* `serialize_bls_key` takes a `secret_key` of type `BlsSecretKey` and a `path` of type `impl AsRef<Path>`.
* `deserialize_bls_key` takes a `path` of type `impl AsRef<Path>`.
Method returns:
* `validate_sk_for_url` returns a `Result<String>` where the `Ok` variant contains the XOR name of the public key derived from the provided secret key as a hex encoded string, and the `Err` variant contains an error.
* `new_keypair_with_pk_url` returns a `Result<(Keypair, SafeUrl)>` where the `Ok` variant contains a BLS keypair of type `Keypair` and a `SafeUrl` object, and the `Err` variant contains an error.
* `serialize_bls_key` returns a `Result<()>` where the `Ok` variant indicates
I think the best comments are those that tell you what the function does in plain English.
i.e.
// This function takes a SecretKey and Data and returns a signature over the data
// Internally it uses ED25519 to create the signature
// The Data is a Vec and the SecretKey is a type form the ed25519 crate
You have to remember, everyone else in the Maidsafe team is a lot smarter than me!
This is a pretty good result I’d say.
===
Can you generate doc comments for this function?
pub async fn validate_sk_for_url(&self, secret_key: &SecretKey, url: &str) -> Result<String> {
let derived_xorname = match secret_key {
SecretKey::Ed25519(sk) => {
let pk: ed25519_dalek::PublicKey = sk.into();
XorName(pk.to_bytes())
}
_ => {
return Err(Error::InvalidInput(
"Cannot form a keypair from a BlsKeyShare at this time.".to_string(),
))
}
};
let safeurl = self.parse_and_resolve_url(url).await?;
if safeurl.xorname() != derived_xorname {
Err(Error::InvalidInput(
"The URL doesn't correspond to the public key derived from the provided secret key"
.to_string(),
))
} else {
Ok(encode(derived_xorname))
}
}
===
/// Validate a secret key for a given URL
///
/// # Arguments
///
/// * `secret_key` - a `SecretKey` object used to derive a public key
/// * `url` - a string representing a URL
///
/// # Returns
///
/// Returns `Result` containing the encoded XorName if validation is successful, otherwise
/// returns an `Error` with a description of the issue.
///
/// # Example
///
/// ```
/// let sk = SecretKey::Ed25519(ed25519_dalek::SecretKey::generate(&mut thread_rng()));
/// let url = "safe://hfjdskf";
/// let result = validate_sk_for_url(&sk, &url).await;
/// assert!(result.is_ok());
///
I might actually start using this when I add new code from now. Doing that on your own in a way that you can get it to come out nice in docs.rs is pretty tedious.
Please document the following code in simple English pasted
register.rs
This code is a Rust implementation of the SAFE Network's `Safe` struct, which provides methods for interacting with the network. It includes methods for creating, reading, and fetching data from Registers on the network. A Register is a data structure on the SAFE Network that can store multiple entries, each with its own unique hash.
The `register_create` method is used to create a new Register on the network with the given name, tag, and content type. The Register's owner will be the client's public key. If a name is not provided, a random XorName will be generated.
The `register_read` method is used to read the values of a Register on the network by providing a URL of the Register. It returns a `BTreeSet` of tuples containing the entry hash and the entry itself.
The `register_read_entry` method is used to read a single entry of a Register on the network by providing the URL and the entry hash. It returns the entry itself.
The `register_fetch_entries` method is used to fetch a Register from a `SafeUrl` without performing any type of URL resolution. It returns a `BTreeSet` of tuples containing the entry hash and the entry itself.
The `register_fetch_entry` method is used to fetch a single entry of a Register on the network by providing the URL and the entry hash. It returns the entry itself.
The `get_register_address` method is used to get the Register address from a `SafeUrl`.
The `get_safe_client` method is used to get a client for interacting with the SAFE Network.
There are also some other methods and types used in this code, such as `XorUrl`, `ContentType`, `Error`, `Result`, `BTreeMap`, `log`, `rand`, `tracing`, and `xor_name`.
This is one of the issues we will face, when people relate to AIs as if they are human. Much like thinking that psychopathic entities like corporations “can be trusted” like humans, or that they give a damn what harm they do to humans or the planet. It is a terrible vulnerability that we default to empathising with things that will happily kill us!
I actually also say please and thank you to it sometimes. The reason is because I don’t want to get used to the demand style questioning and potentially carry that over into my human interactions. For me, being polite is extremely important in human interaction.
I don’t and it doesn’t affect how I treat humans because I know it is a robot. I speak to it much like I would construct a Google search - I’m thinking about what I want and how it will interpret the words, carefully constructing the instructions as much like I write code as a sentence of English, so it isn’t easy for me to confuse that with how I relate to people. I’d never do that writing here for example.
I know what you’re saying, but I think there is a genuine concern that folk, particularly who are growing up using the technology, could get really used to barking orders at it (it’s not gonna be long before it has an Alexa-style interface too), which will potentially form habits that can carry over into their interactions with humans.
Surely we want our future overlords to say please when they are rounding us up into whatever terrifying future they have decided is best for us mere mortals
