Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Consider linking to documentation of underlying libssh2 functions #282

Open
grembo opened this issue Feb 9, 2023 · 0 comments
Open

Consider linking to documentation of underlying libssh2 functions #282

grembo opened this issue Feb 9, 2023 · 0 comments

Comments

@grembo
Copy link

grembo commented Feb 9, 2023

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants