Fix documentation warnings

src/enums.rs

@@ -355,17 +355,22 @@ impl From<sys::gsl_integration_qawo_enum> for IntegrationQawo {
     }
 }
 
-/// Used by VegasMonteCarlo struct
+/// Used by [`VegasParams`][crate::VegasParams].
 ///
-/// The possible choices are GSL_VEGAS_MODE_IMPORTANCE, GSL_VEGAS_MODE_
-/// STRATIFIED, GSL_VEGAS_MODE_IMPORTANCE_ONLY. This determines whether vegas
-/// will use importance sampling or stratified sampling, or whether it can pick on
-/// its own. In low dimensions vegas uses strict stratified sampling (more precisely,
-/// stratified sampling is chosen if there are fewer than 2 bins per box).
+/// This determines whether vegas will use importance sampling or
+/// stratified sampling, or whether it can pick on its own.  In low
+/// dimensions vegas uses strict stratified sampling (more precisely,
+/// stratified sampling is chosen if there are fewer than 2 bins per
+/// box).
 #[derive(Clone, PartialEq, PartialOrd, Debug, Copy)]
 pub enum VegasMode {
+    /// Importance sampling: allocate more sample points where the
+    /// integrand is larger.
     Importance,
+    /// Exclusively use importance sampling without any stratification.
     ImportanceOnly,
+    /// Stratified sampling: divides the integration region into
+    /// sub-regions and sample each sub-region separately.
     Stratified,
 }
 

src/types/basis_spline.rs

@@ -24,8 +24,9 @@ B_(i,k)(x) = [(x - t_i)/(t_(i+k-1) - t_i)] B_(i,k-1)(x)
 for i = 0, …, n-1. The common case of cubic B-splines is given by k = 4. The above recurrence
 relation can be evaluated in a numerically stable way by the de Boor algorithm.
 
-If we define appropriate knots on an interval [a,b] then the B-spline basis functions form a
-complete set on that interval. Therefore we can expand a smoothing function as
+If we define appropriate knots on an interval \[a,b\] then the
+B-spline basis functions form a complete set on that interval.
+Therefore we can expand a smoothing function as
 
 f(x) = \sum_i c_i B_(i,k)(x)
 
@@ -83,8 +84,9 @@ impl BSpLineWorkspace {
         result_handler!(ret, ())
     }
 
-    /// This function assumes uniformly spaced breakpoints on [a,b] and constructs the corresponding
-    /// knot vector using the previously specified nbreak parameter.
+    /// This function assumes uniformly spaced breakpoints on \[a,b\]
+    /// and constructs the corresponding knot vector using the previously
+    /// specified nbreak parameter.
     /// The knots are stored in w->knots.
     #[doc(alias = "gsl_bspline_knots_uniform")]
     pub fn knots_uniform(&mut self, a: f64, b: f64) -> Result<(), Value> {

src/types/chebyshev.rs

@@ -15,8 +15,9 @@ For further information see Abramowitz & Stegun, Chapter 22.
 
 ## Definitions
 
-The approximation is made over the range [a,b] using order+1 terms, including the coefficient
-`c[0]`. The series is computed using the following convention,
+The approximation is made over the range \[a,b\] using order+1 terms,
+including the coefficient `c[0]`.  The series is computed using the
+following convention,
 
 f(x) = (c_0 / 2) + \sum_{n=1} c_n T_n(x)
 

src/types/discrete_hankel.rs

@@ -31,14 +31,18 @@ g_m = (2 / j_(\nu,M)^2)
       \sum_{k=1}^{M-1} f(j_(\nu,k)/j_(\nu,M))
           (J_\nu(j_(\nu,m) j_(\nu,k) / j_(\nu,M)) / J_(\nu+1)(j_(\nu,k))^2).
 
-It is this discrete expression which defines the discrete Hankel transform. The kernel in the
-summation above defines the matrix of the \nu-Hankel transform of size M-1. The coefficients of this
-matrix, being dependent on \nu and M, must be precomputed and stored; the gsl_dht object
-encapsulates this data. The allocation function gsl_dht_alloc returns a gsl_dht object which must be
-properly initialized with gsl_dht_init before it can be used to perform transforms on data sample
-vectors, for fixed \nu and M, using the gsl_dht_apply function. The implementation allows a scaling
-of the fundamental interval, for convenience, so that one can assume the function is defined on the
-interval [0,X], rather than the unit interval.
+It is this discrete expression which defines the discrete Hankel
+transform. The kernel in the summation above defines the matrix of the
+\nu-Hankel transform of size M-1. The coefficients of this matrix,
+being dependent on \nu and M, must be precomputed and stored; the
+gsl_dht object encapsulates this data. The allocation function
+gsl_dht_alloc returns a gsl_dht object which must be properly
+initialized with gsl_dht_init before it can be used to perform
+transforms on data sample vectors, for fixed \nu and M, using the
+gsl_dht_apply function. The implementation allows a scaling of the
+fundamental interval, for convenience, so that one can assume the
+function is defined on the interval \[0,X\], rather than the unit
+interval.
 
 Notice that by assumption f(t) vanishes at the endpoints of the interval, consistent with the
 inversion formula and the sampling formula given above. Therefore, this transform corresponds to an

src/types/histograms.rs

@@ -319,13 +319,16 @@ impl Histogram {
 }
 
 ffi_wrapper!(HistogramPdf, *mut sys::gsl_histogram_pdf, gsl_histogram_pdf_free,
-"The probability distribution function for a histogram consists of a set of bins which measure the \
-probability of an event falling into a given range of a continuous variable x. A probability \
-distribution function is defined by the following struct, which actually stores the cumulative \
-probability distribution function. This is the natural quantity for generating samples via the \
-inverse transform method, because there is a one-to-one mapping between the cumulative probability \
-distribution and the range [0,1]. It can be shown that by taking a uniform random number in this \
-range and finding its corresponding coordinate in the cumulative probability distribution we obtain \
+    "The probability distribution function for a histogram consists of \
+a set of bins which measure the probability of an event falling into a \
+given range of a continuous variable x. A probability distribution \
+function is defined by the following struct, which actually stores the \
+cumulative probability distribution function.  This is the natural \
+quantity for generating samples via the inverse transform method, \
+because there is a one-to-one mapping between the cumulative probability \
+distribution and the range \\[0,1\\]. It can be shown that by taking \
+a uniform random number in this range and finding its corresponding \
+coordinate in the cumulative probability distribution we obtain \
 samples with the desired probability distribution.");
 
 impl HistogramPdf {

src/types/integration.rs

@@ -788,9 +788,11 @@ impl GLFixedTable {
         }
     }
 
-    /// For i in [0, …, t->n - 1], this function obtains the i-th Gauss-Legendre point xi and weight
-    /// wi on the interval [a,b]. The points and weights are ordered by increasing point value. A
-    /// function f may be integrated on [a,b] by summing wi * f(xi) over i.
+    /// For i in \[0, …, t->n - 1\], this function obtains the i-th
+    /// Gauss-Legendre point xi and weight wi on the interval \[a,b\].
+    /// The points and weights are ordered by increasing point value.
+    /// A function f may be integrated on \[a,b\] by summing wi *
+    /// f(xi) over i.
     ///
     /// Returns `(xi, wi)` if it succeeded.
     #[doc(alias = "gsl_integration_glfixed_point")]

src/types/mod.rs

@@ -2,6 +2,8 @@
 // A rust binding for the GSL library by Guillaume Gomez ([email protected])
 //
 
+//! GLS types (reexported into the root `rgsl`).
+
 pub use self::basis_spline::BSpLineWorkspace;
 
 pub use self::chebyshev::ChebSeries;

src/types/monte_carlo.rs

@@ -474,38 +474,48 @@ pub struct VegasParams<'a> {
 }
 
 impl<'a> VegasParams<'a> {
-    /// alpha: The parameter alpha controls the stiffness of the rebinning algorithm. It is typically
-    /// set between one and two. A value of zero prevents rebinning of the grid. The default
-    /// value is 1.5.
+    /// `alpha`: The parameter `alpha` controls the stiffness of the
+    /// rebinning algorithm. It is typically set between one and two.
+    /// A value of zero prevents rebinning of the grid.  The default
+    /// value is `1.5`.
     ///
-    /// iterations: The number of iterations to perform for each call to the routine. The default value
-    /// is 5 iterations.
+    /// `iterations`: The number of iterations to perform for each
+    /// call to the routine.  The default value is `5` iterations.
     ///
-    /// stage: Setting this determines the stage of the calculation. Normally, stage = 0 which begins
-    /// with a new uniform grid and empty weighted average. Calling vegas with stage =
-    /// 1 retains the grid from the previous run but discards the weighted average, so that
-    /// one can “tune” the grid using a relatively small number of points and then do a large
-    /// run with stage = 1 on the optimized grid. Setting stage = 2 keeps the grid and the
-    /// weighted average from the previous run, but may increase (or decrease) the number
-    /// of histogram bins in the grid depending on the number of calls available. Choosing
-    /// stage = 3 enters at the main loop, so that nothing is changed, and is equivalent to
-    /// performing additional iterations in a previous call.
+    /// `stage`: Setting this determines the stage of the
+    /// calculation. Normally, stage = 0 which begins with a new
+    /// uniform grid and empty weighted average. Calling vegas with
+    /// stage = 1 retains the grid from the previous run but discards
+    /// the weighted average, so that one can “tune” the grid using a
+    /// relatively small number of points and then do a large run with
+    /// stage = 1 on the optimized grid. Setting stage = 2 keeps the
+    /// grid and the weighted average from the previous run, but may
+    /// increase (or decrease) the number of histogram bins in the
+    /// grid depending on the number of calls available. Choosing
+    /// stage = 3 enters at the main loop, so that nothing is changed,
+    /// and is equivalent to performing additional iterations in a
+    /// previous call.
     ///
-    /// mode: The possible choices are GSL_VEGAS_MODE_IMPORTANCE, GSL_VEGAS_MODE_
-    /// STRATIFIED, GSL_VEGAS_MODE_IMPORTANCE_ONLY. This determines whether vegas
-    /// will use importance sampling or stratified sampling, or whether it can pick on
-    /// its own. In low dimensions vegas uses strict stratified sampling (more precisely,
-    /// stratified sampling is chosen if there are fewer than 2 bins per box).
+    /// `mode`: The possible choices are
+    /// [`VegasMode::Importance`][crate::VegasMode::Importance],
+    /// [`VegasMode::Stratified`][crate::VegasMode::Stratified], and
+    /// [`VegasMode::ImportanceOnly`][crate::VegasMode::ImportanceOnly].
+    /// This determines whether vegas will use importance sampling or
+    /// stratified sampling, or whether it can pick on its own. In low
+    /// dimensions vegas uses strict stratified sampling (more
+    /// precisely, stratified sampling is chosen if there are fewer
+    /// than 2 bins per box).
     ///
-    /// verbosity + stream: These parameters set the level of information printed by vegas.
+    /// `verbosity` and `stream`: These parameters set the level of
+    /// information printed by vegas.
     pub fn new(
         alpha: f64,
         iterations: usize,
         stage: i32,
         mode: crate::VegasMode,
         verbosity: VegasVerbosity,
         stream: Option<&'a mut crate::IOStream>,
-    ) -> Result<VegasParams, String> {
+    ) -> Result<VegasParams<'a>, String> {
         if !verbosity.is_off() && stream.is_none() {
             return Err(
                 "rust-GSL: need to provide an input stream for Vegas Monte Carlo \

src/types/rng.rs

@@ -110,8 +110,11 @@ impl Rng {
         unsafe { sys::gsl_rng_set(self.unwrap_unique(), s as _) }
     }
 
-    /// This function returns a random integer from the generator r. The minimum and maximum values depend on the algorithm used, but all integers in the range [min,max] are equally likely.
-    /// The values of min and max can be determined using the auxiliary functions gsl_rng_max (r) and gsl_rng_min (r).
+    /// This function returns a random integer from the generator r.
+    /// The minimum and maximum values depend on the algorithm used,
+    /// but all integers in the range \[min,max\] are equally likely.
+    /// The values of min and max can be determined using the
+    /// auxiliary functions gsl_rng_max (r) and gsl_rng_min (r).
     #[doc(alias = "gsl_rng_get")]
     pub fn get(&mut self) -> usize {
         unsafe { sys::gsl_rng_get(self.unwrap_shared()) as _ }

src/types/vector.rs

@@ -59,7 +59,7 @@ pub trait Vector<F> {
     fn len(x: &Self) -> usize;
 
     /// The distance in the slice between two consecutive elements of
-    /// the vector in [`Vector::as_slice`] and [`Vector::as_mut_slice`].
+    /// the vector in [`Vector::as_slice`] and [`VectorMut::as_mut_slice`].
     fn stride(x: &Self) -> usize;
 
     /// Return a reference to the underlying slice.  Note that the