Add examples (#519)

While starting to use this library, I spent way too much time trying to
perform the 3 following tasks, therefore I thought I would contribute
some examples to the documentation.

The examples should help to:

* Clone/push using SSH
* Stage all files

Author: rgreinho

src/build.rs

@@ -12,6 +12,41 @@ use crate::{CheckoutNotificationType, DiffFile, Remote};
 
 /// A builder struct which is used to build configuration for cloning a new git
 /// repository.
+///
+/// # Example
+///
+/// Cloning using SSH:
+///
+/// ```no_run
+/// use git2::{Cred, Error, RemoteCallbacks};
+/// use std::env;
+/// use std::path::Path;
+///
+///   // Prepare callbacks.
+///   let mut callbacks = RemoteCallbacks::new();
+///   callbacks.credentials(|_url, username_from_url, _allowed_types| {
+///     Cred::ssh_key(
+///       username_from_url.unwrap(),
+///       None,
+///       std::path::Path::new(&format!("{}/.ssh/id_rsa", env::var("HOME").unwrap())),
+///       None,
+///     )
+///   });
+///
+///   // Prepare fetch options.
+///   let mut fo = git2::FetchOptions::new();
+///   fo.remote_callbacks(callbacks);
+///
+///   // Prepare builder.
+///   let mut builder = git2::build::RepoBuilder::new();
+///   builder.fetch_options(fo);
+///
+///   // Clone the project.
+///   builder.clone(
+///     "[email protected]:rust-lang/git2-rs.git",
+///     Path::new("/tmp/git2-rs"),
+///   );
+/// ```
 pub struct RepoBuilder<'cb> {
     bare: bool,
     branch: Option<CString>,

src/index.rs

@@ -268,6 +268,19 @@ impl Index {
     /// updated in the index. Returning zero will add the item to the index,
     /// greater than zero will skip the item, and less than zero will abort the
     /// scan an return an error to the caller.
+    ///
+    /// # Example
+    ///
+    /// Emulate `git add *`:
+    ///
+    /// ```no_run
+    /// use git2::{Index, IndexAddOption, Repository};
+    ///
+    /// let repo = Repository::open("/path/to/a/repo").expect("failed to open");
+    /// let mut index = repo.index().expect("cannot get the Index file");
+    /// index.add_all(["*"].iter(), IndexAddOption::DEFAULT, None);
+    /// index.write();
+    /// ```
     pub fn add_all<T, I>(
         &mut self,
         pathspecs: I,

src/lib.rs

@@ -57,6 +57,8 @@
 //! };
 //! ```
 //!
+//! To clone using SSH, refer to [RepoBuilder](./build/struct.RepoBuilder.html).
+//!
 //! ## Working with a `Repository`
 //!
 //! All deriviative objects, references, etc are attached to the lifetime of the

src/remote_callbacks.rs

@@ -76,6 +76,26 @@ impl<'a> RemoteCallbacks<'a> {
     }
 
     /// The callback through which to fetch credentials if required.
+    ///
+    /// # Example
+    ///
+    /// Prepare a callback to authenticate using the `$HOME/.ssh/id_rsa` SSH key, and
+    /// extracting the username from the URL (i.e. [email protected]:rust-lang/git2-rs.git):
+    ///
+    /// ```no_run
+    /// use git2::{Cred, RemoteCallbacks};
+    /// use std::env;
+    ///
+    /// let mut callbacks = RemoteCallbacks::new();
+    /// callbacks.credentials(|_url, username_from_url, _allowed_types| {
+    ///   Cred::ssh_key(
+    ///     username_from_url.unwrap(),
+    ///     None,
+    ///     std::path::Path::new(&format!("{}/.ssh/id_rsa", env::var("HOME").unwrap())),
+    ///     None,
+    ///   )
+    /// });
+    /// ```
     pub fn credentials<F>(&mut self, cb: F) -> &mut RemoteCallbacks<'a>
     where
         F: FnMut(&str, Option<&str>, CredentialType) -> Result<Cred, Error> + 'a,