Sync config docs (#643)

* Sync Config docs with libgit's docs.

* Fix links.

Rustdoc now warns about these not being properly linked.

Author: ehuss

src/apply.rs

@@ -1,12 +1,12 @@
 //! git_apply support
-//! see original: https://github.com/libgit2/libgit2/blob/master/include/git2/apply.h
+//! see original: <https://github.com/libgit2/libgit2/blob/master/include/git2/apply.h>
 
 use crate::{panic, raw, util::Binding, DiffDelta, DiffHunk};
 use libc::c_int;
 use std::{ffi::c_void, mem};
 
 /// Possible application locations for git_apply
-/// see https://libgit2.org/libgit2/#HEAD/type/git_apply_options
+/// see <https://libgit2.org/libgit2/#HEAD/type/git_apply_options>
 #[derive(Copy, Clone, Debug)]
 pub enum ApplyLocation {
     /// Apply the patch to the workdir

src/config.rs

@@ -149,6 +149,8 @@ impl Config {
 
     /// Remove multivar config variables in the config file with the highest level (usually the
     /// local one).
+    ///
+    /// The regular expression is applied case-sensitively on the value.
     pub fn remove_multivar(&mut self, name: &str, regexp: &str) -> Result<(), Error> {
         let name = CString::new(name)?;
         let regexp = CString::new(regexp)?;
@@ -204,6 +206,8 @@ impl Config {
     ///
     /// This is the same as `get_bytes` except that it may return `Err` if
     /// the bytes are not valid utf-8.
+    ///
+    /// This method will return an error if this `Config` is not a snapshot.
     pub fn get_str(&self, name: &str) -> Result<&str, Error> {
         str::from_utf8(self.get_bytes(name)?)
             .map_err(|_| Error::from_str("configuration value is not valid utf8"))
@@ -223,6 +227,10 @@ impl Config {
 
     /// Get the value of a string config variable as an owned string.
     ///
+    /// All config files will be looked into, in the order of their
+    /// defined level. A higher level means a higher priority. The
+    /// first occurrence of the variable will be returned here.
+    ///
     /// An error will be returned if the config value is not valid utf-8.
     pub fn get_string(&self, name: &str) -> Result<String, Error> {
         let ret = Buf::new();
@@ -235,7 +243,15 @@ impl Config {
             .map_err(|_| Error::from_str("configuration value is not valid utf8"))
     }
 
-    /// Get the value of a path config variable as an owned .
+    /// Get the value of a path config variable as an owned `PathBuf`.
+    ///
+    /// A leading '~' will be expanded to the global search path (which
+    /// defaults to the user's home directory but can be overridden via
+    /// [`raw::git_libgit2_opts`].
+    ///
+    /// All config files will be looked into, in the order of their
+    /// defined level. A higher level means a higher priority. The
+    /// first occurrence of the variable will be returned here.
     pub fn get_path(&self, name: &str) -> Result<PathBuf, Error> {
         let ret = Buf::new();
         let name = CString::new(name)?;
@@ -260,6 +276,10 @@ impl Config {
     /// If `glob` is `Some`, then the iterator will only iterate over all
     /// variables whose name matches the pattern.
     ///
+    /// The regular expression is applied case-sensitively on the normalized form of
+    /// the variable name: the section and variable parts are lower-cased. The
+    /// subsection is left unchanged.
+    ///
     /// # Example
     ///
     /// ```
@@ -293,6 +313,10 @@ impl Config {
     ///
     /// If `regexp` is `Some`, then the iterator will only iterate over all
     /// values which match the pattern.
+    ///
+    /// The regular expression is applied case-sensitively on the normalized form of
+    /// the variable name: the section and variable parts are lower-cased. The
+    /// subsection is left unchanged.
     pub fn multivar(&self, name: &str, regexp: Option<&str>) -> Result<ConfigEntries<'_>, Error> {
         let mut ret = ptr::null_mut();
         let name = CString::new(name)?;
@@ -363,6 +387,8 @@ impl Config {
 
     /// Set the value of an multivar config variable in the config file with the
     /// highest level (usually the local one).
+    ///
+    /// The regular expression is applied case-sensitively on the value.
     pub fn set_multivar(&mut self, name: &str, regexp: &str, value: &str) -> Result<(), Error> {
         let name = CString::new(name)?;
         let regexp = CString::new(regexp)?;
@@ -398,6 +424,7 @@ impl Config {
     }
 
     /// Parse a string as a bool.
+    ///
     /// Interprets "true", "yes", "on", 1, or any non-zero number as true.
     /// Interprets "false", "no", "off", 0, or an empty string as false.
     pub fn parse_bool<S: IntoCString>(s: S) -> Result<bool, Error> {

src/repo.rs

@@ -313,7 +313,7 @@ impl Repository {
     /// Find a single object and intermediate reference by a revision string.
     ///
     /// See `man gitrevisions`, or
-    /// http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions for
+    /// <http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions> for
     /// information on the syntax accepted.
     ///
     /// In some cases (`@{<-n>}` or `<branchname>@{upstream}`), the expression

src/tagforeach.rs

@@ -1,5 +1,5 @@
 //! git_tag_foreach support
-//! see original: https://libgit2.org/libgit2/#HEAD/group/tag/git_tag_foreach
+//! see original: <https://libgit2.org/libgit2/#HEAD/group/tag/git_tag_foreach>
 
 use crate::{panic, raw, util::Binding, Oid};
 use libc::{c_char, c_int};
@@ -16,7 +16,7 @@ pub(crate) struct TagForeachData<'a> {
 }
 
 /// c callback forwarding to rust callback inside `TagForeachData`
-/// see original: https://libgit2.org/libgit2/#HEAD/group/callback/git_tag_foreach_cb
+/// see original: <https://libgit2.org/libgit2/#HEAD/group/callback/git_tag_foreach_cb>
 pub(crate) extern "C" fn tag_foreach_cb(
     name: *const c_char,
     oid: *mut git_oid,