Beef up documentation

7 files changed, 88 insertions, 0 deletions

diff --git a/src/agent.rs b/src/agent.rs
index d3e4ed3..130f817 100644
--- a/src/agent.rs
+++ b/src/agent.rs
@@ -5,17 +5,22 @@ use std::str;
 
 use {raw, Session, Error};
 
+/// A structure representing a connection to an SSH agent.
+///
+/// Agents can be used to authenticate a session.
 pub struct Agent<'a> {
     raw: *mut raw::LIBSSH2_AGENT,
     sess: &'a Session,
     marker: marker::NoSync,
 }
 
+/// An iterator over the identities found in an SSH agent.
 pub struct Identities<'a> {
     prev: *mut raw::libssh2_agent_publickey,
     agent: &'a Agent<'a>,
 }
 
+/// A public key which is extracted from an SSH agent.
 pub struct PublicKey<'a> {
     raw: *mut raw::libssh2_agent_publickey,
     marker1: marker::NoSync,
@@ -97,6 +102,10 @@ impl<'a> Iterator<Result<PublicKey<'a>, Error>> for Identities<'a> {
 }
 
 impl<'a> PublicKey<'a> {
+    /// Creates a new public key from its raw counterpart.
+    ///
+    /// Unsafe because the validity of `raw` cannot be guaranteed and there are
+    /// no restrictions on the lifetime returned.
     pub unsafe fn from_raw<'a>(raw: *mut raw::libssh2_agent_publickey)
                                -> PublicKey<'a> {
         PublicKey {
diff --git a/src/channel.rs b/src/channel.rs
index 971e72f..a3a0567 100644
--- a/src/channel.rs
+++ b/src/channel.rs
@@ -6,6 +6,11 @@ use libc::{c_uint, c_int, size_t, c_char, c_void, c_uchar};
 
 use {raw, Session, Error};
 
+/// A channel represents a portion of an SSH connection on which data can be
+/// read and written.
+///
+/// Channels denote all of SCP uploads and downloads, shell sessions, remote
+/// process executions, and other general-purpose sessions.
 pub struct Channel<'a> {
     raw: *mut raw::LIBSSH2_CHANNEL,
     sess: &'a Session,
diff --git a/src/knownhosts.rs b/src/knownhosts.rs
index efdd7ae..0b076a5 100644
--- a/src/knownhosts.rs
+++ b/src/knownhosts.rs
@@ -4,17 +4,35 @@ use libc::{c_int, size_t};
 
 use {raw, Session, Error, KnownHostFileKind, CheckResult};
 
+/// A set of known hosts which can be used to verify the identity of a remote
+/// server.
+//
+// # Example
+//
+// ```
+// # use ssh2::Session;
+// # let session: Session = fail!();
+//
+// let known_hosts = session.known_hosts().unwrap();
+// let (to_find, _) = session.host_key();
+// fail!(); // TODO
+// for host in known_hosts.iter() {
+//     let host = host.unwrap(); // ignore I/O errors.
+// }
+// ```
 pub struct KnownHosts<'a> {
     raw: *mut raw::LIBSSH2_KNOWNHOSTS,
     sess: &'a Session,
     marker: marker::NoSync,
 }
 
+/// Iterator over the hosts in a `KnownHosts` structure.
 pub struct Hosts<'a> {
     prev: *mut raw::libssh2_knownhost,
     hosts: &'a KnownHosts<'a>,
 }
 
+/// Structure representing a known host as part of a `KnownHosts` structure.
 pub struct Host<'a> {
     raw: *mut raw::libssh2_knownhost,
     marker1: marker::NoSync,
@@ -202,6 +220,10 @@ impl<'a> Iterator<Result<Host<'a>, Error>> for Hosts<'a> {
 }
 
 impl<'a> Host<'a> {
+    /// Creates a new host from its raw counterpart.
+    ///
+    /// Unsafe as there are no restrictions on the lifetime of the host returned
+    /// and the validity of `raw` is not known.
     pub unsafe fn from_raw<'a>(raw: *mut raw::libssh2_knownhost)
                                -> Host<'a> {
         Host {
diff --git a/src/lib.rs b/src/lib.rs
index 1995ae8..1182fc4 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -49,6 +49,7 @@
 //! ```
 
 #![feature(phase, unsafe_destructor)]
+#![deny(warnings, missing_doc)]
 
 extern crate "libssh2-sys" as raw;
 extern crate libc;
@@ -136,12 +137,14 @@ pub enum SessionFlag {
     Compress = raw::LIBSSH2_FLAG_COMPRESS as int,
 }
 
+#[allow(missing_doc)]
 pub enum HostKeyType {
     TypeUnknown = raw::LIBSSH2_HOSTKEY_TYPE_UNKNOWN as int,
     TypeRsa = raw::LIBSSH2_HOSTKEY_TYPE_RSA as int,
     TypeDss = raw::LIBSSH2_HOSTKEY_TYPE_DSS as int,
 }
 
+#[allow(missing_doc)]
 pub enum MethodType {
     MethodKex = raw::LIBSSH2_METHOD_KEX as int,
     MethodHostKey = raw::LIBSSH2_METHOD_HOSTKEY as int,
@@ -155,19 +158,26 @@ pub enum MethodType {
     MethodLangSc = raw::LIBSSH2_METHOD_LANG_SC as int,
 }
 
+/// When passed to `Channel::flush_stream`, flushes all extended data
+/// substreams.
 pub static FlushExtendedData: uint = -1;
+/// When passed to `Channel::flush_stream`, flushes all substream.
 pub static FlushAll: uint = -2;
+/// Stream ID of the stderr channel for stream-related methods on `Channel`
 pub static ExtendedDataStderr: uint = 1;
 
+#[allow(missing_doc)]
 pub enum HashType {
     HashMd5 = raw::LIBSSH2_HOSTKEY_HASH_MD5 as int,
     HashSha1 = raw:: LIBSSH2_HOSTKEY_HASH_SHA1 as int,
 }
 
+#[allow(missing_doc)]
 pub enum KnownHostFileKind {
     OpenSSH = raw::LIBSSH2_KNOWNHOST_FILE_OPENSSH as int,
 }
 
+/// Possible results of a call to `KnownHosts::check`
 pub enum CheckResult {
     /// Hosts and keys match
     CheckMatch = raw::LIBSSH2_KNOWNHOST_CHECK_MATCH as int,
@@ -179,6 +189,7 @@ pub enum CheckResult {
     CheckFailure = raw::LIBSSH2_KNOWNHOST_CHECK_FAILURE as int,
 }
 
+#[allow(missing_doc)]
 pub enum KnownHostKeyFormat {
     KeyRsa1 = raw::LIBSSH2_KNOWNHOST_KEY_RSA1 as int,
     KeySshRsa = raw::LIBSSH2_KNOWNHOST_KEY_SSHRSA as int,
diff --git a/src/listener.rs b/src/listener.rs
index 52f25ad..5db3b80 100644
--- a/src/listener.rs
+++ b/src/listener.rs
@@ -2,6 +2,10 @@ use std::kinds::marker;
 
 use {raw, Session, Error, Channel};
 
+/// A listener represents a forwarding port from the remote server.
+///
+/// New channels can be accepted from a listener which represent connections on
+/// the remote server's port.
 pub struct Listener<'a> {
     raw: *mut raw::LIBSSH2_LISTENER,
     sess: &'a Session,
diff --git a/src/session.rs b/src/session.rs
index 49948f1..9707a77 100644
--- a/src/session.rs
+++ b/src/session.rs
@@ -8,6 +8,11 @@ use libc::{mod, c_uint, c_int, c_void, c_long};
 use {raw, Error, DisconnectCode, ByApplication, SessionFlag, HostKeyType};
 use {MethodType, Agent, Channel, Listener, HashType, KnownHosts, Sftp};
 
+/// An SSH session, typically representing one TCP connection.
+///
+/// All other structures are based on an SSH session and cannot outlive a
+/// session. Sessions are created and then have the TCP socket handed to them
+/// (via the `handshake` method).
 pub struct Session {
     raw: *mut raw::LIBSSH2_SESSION,
     marker: marker::NoSync,
diff --git a/src/sftp.rs b/src/sftp.rs
index dfaf5ff..346b97c 100644
--- a/src/sftp.rs
+++ b/src/sftp.rs
@@ -5,6 +5,9 @@ use libc::{c_int, c_ulong, c_long, c_uint, size_t};
 
 use {raw, Session, Error};
 
+/// A handle to a remote filesystem over SFTP.
+///
+/// Instances are created through the `sftp` method on a `Session`.
 pub struct Sftp<'a> {
     raw: *mut raw::LIBSSH2_SFTP,
     marker1: marker::NoSync,
@@ -12,22 +15,39 @@ pub struct Sftp<'a> {
     marker3: marker::NoSend,
 }
 
+/// A file handle to an SFTP connection.
+///
+/// Files behave similarly to `std::io::File` in that they are readable and
+/// writable and support operations like stat and seek.
+///
+/// Files are created through `open`, `create`, and `open_mode` on an instance
+/// of `Sftp`.
 pub struct File<'a> {
     raw: *mut raw::LIBSSH2_SFTP_HANDLE,
     sftp: &'a Sftp<'a>,
     marker: marker::NoSync,
 }
 
+/// Metadata information about a remote file.
+///
+/// Fields are not necessarily all provided
 pub struct FileStat {
+    /// File size, in bytes of the file.
     pub size: Option<u64>,
+    /// Owner ID of the file
     pub uid: Option<uint>,
+    /// Owning group of the file
     pub gid: Option<uint>,
+    /// Permissions (mode) of the file
     pub perm: Option<uint>,
+    /// Last access time of the file
     pub atime: Option<uint>,
+    /// Last modification time of the file
     pub mtime: Option<uint>,
 }
 
 bitflags! {
+    #[doc = "Options that can be used to configure how a file is opened"]
     flags OpenFlags: c_ulong {
         #[doc = "Open the file for reading."]
         static Read = raw::LIBSSH2_FXF_READ,
@@ -52,15 +72,26 @@ bitflags! {
 }
 
 bitflags! {
+    #[doc = "Options to `Sftp::rename`"]
     flags RenameFlags: c_long {
+        #[doc = "In a rename operation, overwrite the destination if it \
+                 already exists. If this flag is not present then it is an \
+                 error if the destination already exists"]
         static Overwrite = raw::LIBSSH2_SFTP_RENAME_OVERWRITE,
+        #[doc = "Inform the remote that an atomic rename operation is \
+                 desired if available"]
         static Atomic = raw::LIBSSH2_SFTP_RENAME_ATOMIC,
+        #[doc = "Inform the remote end that the native system calls for \
+                 renaming should be used"]
         static Native = raw::LIBSSH2_SFTP_RENAME_NATIVE
     }
 }
 
+/// How to open a file handle with libssh2.
 pub enum OpenType {
+    /// Specify that a file shoud be opened.
     OpenFile = raw::LIBSSH2_SFTP_OPENFILE as int,
+    /// Specify that a directory should be opened.
     OpenDir = raw::LIBSSH2_SFTP_OPENDIR as int,
 }
 
@@ -331,6 +362,7 @@ impl<'a> File<'a> {
         }
     }
 
+    #[allow(missing_doc)] // sure wish I knew what this did...
     pub fn statvfs(&mut self) -> Result<raw::LIBSSH2_SFTP_STATVFS, Error> {
         unsafe {
             let mut ret = mem::zeroed();