Merge #330

330: Disallow warnings in doctests r=metasim a=metasim

- [x] I agree to follow the project's [code of conduct](https://github.com/georust/gdal/blob/master/CODE_OF_CONDUCT.md).
- [ ] I added an entry to `CHANGES.md` if knowledge of this change could be valuable to users.
---

This helps us ensure the documentation abides by deprecations.


Co-authored-by: Simeon H.K. Fitch <[email protected]>

.cargo/config.toml

@@ -0,0 +1,3 @@
+[alias]
+# Run doctests, displaying compiler output
+dto = "test --doc -- --show-output"

src/dataset.rs

@@ -637,18 +637,18 @@ impl Dataset {
     /// Create a new layer with an empty name, no spatial reference, and unknown geometry type:
     ///
     /// ```
-    /// # use gdal::Driver;
-    /// # let driver = Driver::get_by_name("GPKG").unwrap();
+    /// # use gdal::DriverManager;
+    /// # let driver = DriverManager::get_driver_by_name("GPKG").unwrap();
     /// # let mut dataset = driver.create_vector_only("/vsimem/example.gpkg").unwrap();
     /// let blank_layer = dataset.create_layer(Default::default()).unwrap();
     /// ```
     ///
     /// Create a new named line string layer using WGS84:
     ///
     /// ```
-    /// # use gdal::{Driver, LayerOptions};
+    /// # use gdal::{DriverManager, LayerOptions};
     /// # use gdal::spatial_ref::SpatialRef;
-    /// # let driver = Driver::get_by_name("GPKG").unwrap();
+    /// # let driver = DriverManager::get_driver_by_name("GPKG").unwrap();
     /// # let mut dataset = driver.create_vector_only("/vsimem/example.gpkg").unwrap();
     /// let roads = dataset.create_layer(LayerOptions {
     ///     name: "roads",
@@ -806,7 +806,7 @@ impl Dataset {
     /// }
     /// #
     /// # fn main() -> gdal::errors::Result<()> {
-    /// #     let driver = gdal::Driver::get_by_name("SQLite")?;
+    /// #     let driver = gdal::DriverManager::get_driver_by_name("SQLite")?;
     /// #     let mut dataset = driver.create_vector_only(":memory:")?;
     /// #     create_point_grid(&mut dataset)?;
     /// #     assert_eq!(dataset.layer(0)?.features().count(), 10000);

src/driver.rs

@@ -43,62 +43,19 @@ pub struct Driver {
 
 impl Driver {
     /// Returns the driver with the given short name or [`Err`] if not found.
-    ///
-    /// See also: [`count`](Self::count), [`get`](Self::get)
-    ///
-    /// # Example
-    ///
-    /// ```rust, no_run
-    /// use gdal::Driver;
-    /// # fn main() -> gdal::errors::Result<()> {
-    /// let cog_driver = Driver::get_by_name("COG")?;
-    /// println!("{}", cog_driver.long_name());
-    /// # Ok(())
-    /// # }
-    /// ```
-    /// ```text
-    /// Cloud optimized GeoTIFF generator
-    /// ```
     #[deprecated(note = "Please use `DriverManager::get_driver_by_name()` instead")]
     pub fn get_by_name(name: &str) -> Result<Driver> {
         DriverManager::get_driver_by_name(name)
     }
 
     /// Returns the driver with the given index, which must be less than the value returned by
     /// `Driver::count()`.
-    ///
-    /// See also: [`count`](Self::count)
-    ///
-    /// # Example
-    ///
-    /// ```rust, no_run
-    /// use gdal::Driver;
-    /// # fn main() -> gdal::errors::Result<()> {
-    /// assert!(Driver::count() > 0);
-    /// let d = Driver::get(0)?;
-    /// println!("'{}' is '{}'", d.short_name(), d.long_name());
-    /// # Ok(())
-    /// # }
-    /// ```
-    /// ```text
-    /// 'VRT' is 'Virtual Raster'
-    /// ```
     #[deprecated(note = "Please use `DriverManager::get_driver()` instead")]
     pub fn get(index: usize) -> Result<Driver> {
         DriverManager::get_driver(index)
     }
 
     /// Returns the number of registered drivers.
-    ///
-    /// # Example
-    ///
-    /// ```rust, no_run
-    /// use gdal::Driver;
-    /// println!("{} drivers are registered", Driver::count());
-    /// ```
-    /// ```text
-    /// 203 drivers are registered
-    /// ```
     #[deprecated(note = "Please use `DriverManager::count()` instead")]
     pub fn count() -> usize {
         DriverManager::count()

src/lib.rs

@@ -2,6 +2,7 @@
 #![crate_type = "lib"]
 // Enable `doc_cfg` features when `docsrs` is defined by docs.rs config
 #![cfg_attr(docsrs, feature(doc_cfg))]
+#![doc(test(attr(deny(warnings), allow(dead_code, unused_variables))))]
 
 //! # GDAL
 //! [GDAL](http://gdal.org/) is a translator and processing library for various raster and vector geospatial data formats.
@@ -39,7 +40,7 @@
 //! but for the maximally impatient, here you go:
 //!
 //! ```rust, no_run
-//! use gdal::{Dataset, Metadata};
+//! use gdal::Dataset;
 //! # fn main() -> gdal::errors::Result<()> {
 //! let ds = Dataset::open("fixtures/m_3607824_se_17_1_20160620_sub.tif")?;
 //! println!("This {} is in '{}' and has {} bands.", ds.driver().long_name(), ds.spatial_ref()?.name()?, ds.raster_count());

src/raster/rasterband.rs

@@ -1048,15 +1048,15 @@ impl Debug for ColorEntry {
 /// # Example
 ///
 /// ```rust, no_run
-/// use gdal::{Dataset, Driver};
+/// use gdal::{Dataset, DriverManager};
 /// use gdal::raster::{ColorEntry, ColorTable, PaletteInterpretation};
 /// # fn main() -> gdal::errors::Result<()> {
 ///
 /// // Open source multinomial classification raster
 /// let ds = Dataset::open("fixtures/labels.tif")?;
 ///
 /// // Create in-memory copy to mutate
-/// let mem_driver = Driver::get_by_name("MEM")?;
+/// let mem_driver = DriverManager::get_driver_by_name("MEM")?;
 /// let ds = ds.create_copy(&mem_driver, "<mem>", &[])?;
 /// let mut band = ds.rasterband(1)?;
 /// assert!(band.color_table().is_none());
@@ -1070,7 +1070,7 @@ impl Debug for ColorEntry {
 /// band.set_color_table(&ct);
 ///
 /// // Render a PNG
-/// let png_driver = Driver::get_by_name("PNG")?;
+/// let png_driver = DriverManager::get_driver_by_name("PNG")?;
 /// ds.create_copy(&png_driver, "/tmp/labels.png", &[])?;
 ///
 /// # Ok(())
@@ -1107,8 +1107,7 @@ impl<'a> ColorTable<'a> {
     /// # Example
     ///
     /// ```rust, no_run
-    /// use gdal::{Dataset, Driver};
-    /// use gdal::raster::{ColorEntry, ColorTable, PaletteInterpretation};
+    /// use gdal::raster::{ColorEntry, ColorTable};
     /// # fn main() -> gdal::errors::Result<()> {
     /// // Create a 16 step blue to white color table.
     /// let ct = ColorTable::color_ramp(

src/vector/mod.rs

@@ -9,7 +9,6 @@
 //! // The `LayerAccess` trait enables reading of vector specific fields from the `Dataset`.
 //! use gdal::vector::LayerAccess;
 //! # fn main() -> gdal::errors::Result<()> {
-//! use gdal::errors::GdalError;
 //! use gdal::vector::geometry_type_to_name;
 //! let dataset = Dataset::open("fixtures/roads.geojson")?;
 //! println!("Dataset description: {}", dataset.description()?);