alexcrichton / ssh2-rs

Rust bindings for libssh2
https://docs.rs/ssh2
Apache License 2.0
467 stars 142 forks source link

Consider linking to documentation of underlying libssh2 functions #282

Open grembo opened 1 year ago

grembo commented 1 year ago

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.

The underlying libssh2 documentation is very specific:

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.