Comments are sometimes not really helpful and require digging in the underlying C-sources or at least libssh2's documentation.
Example:
// Checks a host and its associated key against the collection of known
/// hosts, and returns info back about the (partially) matched entry.
///
/// The host name can be the IP numerical address of the host or the full
/// name. The key must be the raw data of the key.
pub fn check(&self, host: &str, key: &[u8]) -> CheckResult {
self.check_port_(host, -1, key)
}
/// Same as `check`, but takes a port as well.
pub fn check_port(&self, host: &str, port: u16, key: &[u8]) -> CheckResult {
self.check_port_(host, port as i32, key)
}
So, Same as "check", but takes a port as well. isn't super helpful to the reader.
port is the port number used by the host (or a negative number to check the generic host). If the port number is given, libssh2 will check the key for the specific host + port number combination in addition to the plain host name only check.
(emphasis added).
So I wonder if just adding hyperlinks to libssh2's documentation would be helpful to users of the crate (vs. duplicating and synching upstream documentation) to clarify the details of the underlying implementation.
Comments are sometimes not really helpful and require digging in the underlying C-sources or at least libssh2's documentation.
Example:
So,
Same as "check", but takes a port as well.
isn't super helpful to the reader.The underlying libssh2 documentation is very specific:
So I wonder if just adding hyperlinks to libssh2's documentation would be helpful to users of the crate (vs. duplicating and synching upstream documentation) to clarify the details of the underlying implementation.