Consider linking to documentation of underlying libssh2 functions
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 566
- Forks
- 163
- Avg merge
- 4h 51m
- Merged PRs (30d)
- 2
Description
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.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the check and check_port API comments shown in the issue and compare them with the linked libssh2_knownhost_checkp documentation. Identify the relevant Rust documentation comments and add links to the underlying libssh2 documentation where they clarify behavior; done when users can follow the links without duplicating upstream text.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100