docs: cleanup

src/bounds.rs

@@ -7,6 +7,7 @@ use crate::{transform::RoundingMode, Point, Result, Transform, Vector};
 pub struct Bounds {
     /// The minimum values.
     pub min: Vector<f64>,
+
     /// The maximum values.
     pub max: Vector<f64>,
 }

src/color.rs

@@ -3,8 +3,10 @@
 pub struct Color {
     /// Red channel.
     pub red: u16,
+
     /// Green channel.
     pub green: u16,
+
     /// Blue channel.
     pub blue: u16,
 }

src/feature.rs

@@ -1,7 +1,8 @@
-//! Programatically determine whether a las version supports a feature.
+//! Programmatically determine whether a las version supports a feature.
 //!
-//! Features are structures that implement the `Feature` trait. The most common way to use features
-//! is via `Version::supports` or `Version::verify_support_for`:
+//! Features are structures that implement the [Feature] trait. The most common
+//! way to use features is via [Version::supports] or
+//! [Version::verify_support_for]:
 //!
 //! ```
 //! use las::feature::Waveforms;

src/gps_time_type.rs

@@ -4,6 +4,7 @@ pub enum GpsTimeType {
     /// GPS Week Time (the same as previous versions of LAS).
     #[default]
     Week,
+
     /// Standard GPS Time minus 1e9.
     Standard,
 }

src/header/builder.rs

@@ -8,7 +8,7 @@ use crate::{
     Version, Vlr,
 };
 
-/// Builds headers.
+/// Use this structure to build a [Header].
 #[derive(Clone, Debug, Default)]
 pub struct Builder {
     /// The date of file creation.
@@ -26,7 +26,7 @@ pub struct Builder {
     /// A globally unique identifier.
     pub guid: Uuid,
 
-    /// Are the return numbers in this file syntheetic?
+    /// Are the return numbers in this file synthetic?
     pub has_synthetic_return_numbers: bool,
 
     /// Does this file has a WKT CRS?
@@ -167,7 +167,7 @@ impl Builder {
         })
     }
 
-    /// Converts this builder into a `Header`.
+    /// Builds a [Header].
     ///
     /// # Examples
     ///

src/header/mod.rs

@@ -1,8 +1,8 @@
-//! A `Header` describes the configuration and properties of las data.
+//! A [Header] describes the configuration and properties of las data.
 //!
 //! # Reading
 //!
-//! A `Reader` uses a `Header` to expose metadata:
+//! A [Reader](crate::Reader) uses a [Header] to expose metadata:
 //!
 //! ```
 //! use las::{Read, Reader};
@@ -13,21 +13,34 @@
 //!
 //! # Writing
 //!
-//! A `Writer` uses a header to configure how it will write points.  To create a las file, you can
-//! use a `Header` from another file, use the default `Header`, or create one with a `Builder`:
+//! A [Writer](crate::Writer) uses a [Header] to configure how it will write
+//! points.  To create a las file, you can use a [Header] from another file, use
+//! the default [Header], or create one with a [Builder]:
+//!
+//! The default configuration writes to a [Cursor](std::io::Cursor):
+//!
+//! ```
+//! use las::Writer;
+//!
+//! let writer = Writer::default();
+//! ```
+//!
+//! You can copy configuration from an existing file:
 //!
 //! ```
 //! use std::io::Cursor;
-//! use las::{Write, Writer, Builder, Read, Reader, Header};
+//! use las::{Writer, Reader, Read};
 //!
-//! // Copy the configuration from an existing file.
 //! let header = Reader::from_path("tests/data/autzen.las").unwrap().header().clone();
 //! let writer = Writer::new(Cursor::new(Vec::new()), header).unwrap();
+//! ```
 //!
-//! // Use the default configuration, which writes to a `Cursor<Vec<u8>>`.
-//! let writer = Writer::default();
+//! Use a [Builder] to set your own configuration:
+//!
+//! ```
+//! use std::io::Cursor;
+//! use las::{Writer, Builder};
 //!
-//! // Set your own configuration with a `Builder`.
 //! let mut builder = Builder::from((1, 4));
 //! builder.system_identifier = "Synthetic points".to_string();
 //! let header = builder.into_header().unwrap();
@@ -36,8 +49,8 @@
 //!
 //! # Into raw bytes
 //!
-//! A `Header` has a method to turn it into a `raw::Header`, which maps directly onto the bytes of
-//! the las spec:
+//! A [Header] has a method to turn it into a [raw::Header], which maps directly
+//! onto the bytes of the las spec:
 //!
 //! ```
 //! use las::Header;
@@ -140,7 +153,7 @@ pub struct Header {
 
 /// An iterator over a header's variable length records.
 ///
-/// Get this iterator via `vlrs` or `evlrs` methods on `Header`.
+/// Get this iterator via [Header::vlrs] or [Header::evlrs].
 #[derive(Debug)]
 pub struct Vlrs<'a>(Chain<Iter<'a, Vlr>, Iter<'a, Vlr>>);
 
@@ -217,9 +230,10 @@ impl Header {
 
     /// Returns the gps time type.
     ///
-    /// This affects what the gps time values on points means. `GpsTimeType::Week` means that the
-    /// time values are seconds from the start of the week. `GpsTimeType::Standard` means that the
-    /// time values are standard GPS time (satellite gps time) minus 10e9.
+    /// This affects what the gps time values on points means.
+    /// [GpsTimeType::Week] means that the time values are seconds from the
+    /// start of the week. [GpsTimeType::Standard] means that the time values
+    /// are standard GPS time (satellite gps time) minus 10e9.
     ///
     /// # Examples
     ///
@@ -457,7 +471,6 @@ impl Header {
         &self.vlrs
     }
 
-    /// Used by the CompressedPointWriter to add the Laszip Vlr
     #[cfg(feature = "laz")]
     pub(crate) fn vlrs_mut(&mut self) -> &mut Vec<Vlr> {
         &mut self.vlrs

src/lib.rs

@@ -3,14 +3,14 @@
 //!
 //! # Reading
 //!
-//! Create a `Reader` from a `Path`:
+//! Create a [Reader] from a [Path](std::path::Path):
 //!
 //! ```
 //! use las::Reader;
 //! let reader = Reader::from_path("tests/data/autzen.las").unwrap();
 //! ```
 //!
-//! Or anything that implements `Read`:
+//! Or anything that implements [Read](std::io::Read):
 //!
 //! ```
 //! use std::io::BufReader;
@@ -20,22 +20,23 @@
 //! let reader = Reader::new(read).unwrap();
 //! ```
 //!
-//! ## Prefer `BufRead`
+//! ## Prefer [BufRead](std::io::BufRead)
 //!
-//! Your performance will be better if your `Read` is actually a `BufRead`. `Reader::from_path`
-//! takes care of this for you, but `Reader::new` doesn't.
+//! Your performance will be better if your [Read](std::io::Read) is actually a
+//! [BufRead](std::io::BufRead). [Reader::from_path] takes care of this for you,
+//! but [Reader::new] doesn't.
 //!
 //! ## Read points
 //!
-//! Read points one-by-one with `Reader::read`:
+//! Read points one-by-one with [Reader::read]:
 //!
 //! ```
 //! use las::{Read, Reader};
 //! let mut reader = Reader::from_path("tests/data/autzen.las").unwrap();
 //! let point = reader.read().unwrap().unwrap();
 //! ```
 //!
-//! Or iterate over all points with `Reader::points`:
+//! Or iterate over all points with [Reader::points]:
 //!
 //! ```
 //! use las::{Read, Reader};
@@ -55,7 +56,7 @@
 //!
 //! # Writing
 //!
-//! Create a `Writer` from a `Write` and a `Header`:
+//! Create a [Writer] from a [Write](std::io::Write) and a [Header]:
 //!
 //! ```
 //! use std::io::Cursor;
@@ -65,14 +66,14 @@
 //! let writer = Writer::new(write, header).unwrap();
 //! ```
 //!
-//! You can also write out to a path (automatically buffered with `BufWriter`):
+//! You can also write out to a path (automatically buffered with [BufWriter](std::io::BufWriter)):
 //!
 //! ```
 //! use las::Writer;
 //! let writer = Writer::from_path("/dev/null", Default::default());
 //! ```
 //!
-//! Use a `Builder` to customize the las data:
+//! Use a [Builder] to customize the las data:
 //!
 //! ```
 //! use std::io::Cursor;
@@ -87,7 +88,34 @@
 //! let writer = Writer::new(write, header).unwrap();
 //! ```
 //!
-//! If compiled with laz you can compress the data written
+//! ## Prefer [BufWriter](std::io::BufWriter)
+//!
+//! Just like the [Reader], your performance will improve greatly if you use a
+//! [BufWriter](std::io::BufWriter) instead of just a [Write](std::io::Write).
+//!
+//! ## Write points
+//!
+//! Write points one at a time:
+//!
+//! ```
+//! use std::io::Cursor;
+//! use las::{Write, Writer, Point};
+//! let mut writer = Writer::default();
+//! let point = Point { x: 1., y: 2., z: 3., ..Default::default() };
+//! writer.write(point).unwrap();
+//! ```
+//!
+//! # Compression
+//!
+//! The [laz](https://laszip.org/) compression format is the de-facto standard for compression las data.
+//! To enable laz support, enable the `laz` or `laz-parallel` feature:
+//!
+//! ```toml
+//! [dependencies]
+//! las = { version = "0.8", features = ["laz"] }  # or laz-parallel
+//! ```
+//!
+//! Then, you can compress the data when writing:
 //!
 //! ```
 //! use std::io::Cursor;
@@ -96,44 +124,22 @@
 //!
 //! let mut builder = Builder::from((1, 4));
 //! builder.point_format = Format::new(2).unwrap();
-//! // asking to compress data
 //! builder.point_format.is_compressed = true;
 //! let header = builder.into_header().unwrap();
-//!
 //! let write = Cursor::new(Vec::new());
-//! let is_compiled_with_laz = cfg!(feature = "laz");
-//!
-//!
 //! let result =  Writer::new(write, header);
-//! if is_compiled_with_laz {
-//!     assert_eq!(result.is_ok(), true);
+//! if cfg!(feature = "laz") {
+//!     assert!(result.is_ok());
 //! } else {
-//!    assert_eq!(result.is_err(), true);
+//!     assert!(result.is_err());
 //! }
-//!
 //! ```
 //!
-//! The [from_path](writer/struct.Writer.html#method.from_path) will use the extension of the output
-//! file to determine wether the data should be compressed or not
-//! 'laz' => compressed
-//! 'las' => not compressed
-//!
-//! ## Prefer `BufWrite`
+//! [Writer::from_path] will use the extension of the output file to determine
+//! wether the data should be compressed or not:
 //!
-//! Just like the `Reader`, your performance will improve greatly if you use a `BufWrite` instead
-//! of just a `Write`.
-//!
-//! ## Write points
-//!
-//! Write points one at a time:
-//!
-//! ```
-//! use std::io::Cursor;
-//! use las::{Write, Writer, Point};
-//! let mut writer = Writer::default();
-//! let point = Point { x: 1., y: 2., z: 3., ..Default::default() };
-//! writer.write(point).unwrap();
-//! ```
+//! - `.laz`: compressed
+//! - `.las`: not compressed
 
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
 #![deny(
@@ -169,7 +175,7 @@
 #![recursion_limit = "128"]
 
 #[cfg(feature = "laz")]
-mod compression;
+mod laz;
 
 pub mod feature;
 pub mod header;

src/point/format.rs

@@ -22,8 +22,8 @@ fn point_format_id_uncompressed_to_compressed(point_format_id: u8) -> u8 {
 
 /// Point formats are defined by the las spec.
 ///
-/// As of las 1.4, there are eleven point formats (0-10). A new `Format` can be created from its
-/// code and converted back into it:
+/// As of las 1.4, there are eleven point formats (0-10). A new [Format] can be
+/// created from its code and converted back into it:
 ///
 /// ```
 /// use las::point::Format;
@@ -122,6 +122,7 @@ impl Format {
     /// format.extend();
     /// assert!(format.has_gps_time);
     /// assert!(format.is_extended);
+    /// ```
     pub fn extend(&mut self) {
         self.has_gps_time = true;
         self.is_extended = true;

src/point/mod.rs

@@ -38,7 +38,7 @@ pub enum Error {
     #[error("invalid format number: {0}")]
     FormatNumber(u8),
 
-    /// Overlap points are handled by an attribute on `las::Point`, not by a classification.
+    /// Overlap points are handled by an attribute on [Point], not by a classification.
     #[error("overlap points are handled by the `is_overlap` member of `las::Point`, not by classifications")]
     OverlapClassification,
 
@@ -73,6 +73,7 @@ pub struct Point {
     /// there is no way to indicate the "optionalness" of the intensity value and since zero could
     /// be valid intensity, we don't wrap this in an `Option`.
     pub intensity: u16,
+
     /// The pulse return number for a given output pulse.
     pub return_number: u8,
 

src/point/scan_direction.rs

@@ -4,6 +4,7 @@ pub enum ScanDirection {
     /// The scan is moving from the right to the left.
     #[default]
     RightToLeft,
+
     /// The scan is moving from the left to the right.
     LeftToRight,
 }

src/raw/mod.rs

@@ -1,9 +1,10 @@
 //! Raw structures that map directly to their definitions in the las format specifications.
 //!
 //! In general, these structures are "dumb", meaning that they do the least amount of validity
-//! checking possible without losing information. Users should prefer to use the non-raw versions,
-//! e.g. `las::Header` over `las::raw::Header`, in order to ensure that they are following The
-//! Rules. `into_raw` can be used to create the raw versions:
+//! checking possible without losing information. Users should prefer to use the
+//! non-raw versions, e.g. [Header] should be preferred over
+//! [raw::Header](crate::raw::Header), in order to ensure that they are
+//! following The Rules. `into_raw` can be used to create the raw versions:
 //!
 //! ```
 //! use las::{Vlr, Header, Point};
@@ -12,8 +13,8 @@
 //! let raw_point = Point::default().into_raw(&Default::default()).unwrap();
 //! ```
 //!
-//! Raw structures all have `write_to` and `read_from` methods that can be used to put and extract
-//! them from streams of bytes:
+//! Raw structures all have `write_to` and `read_from` methods that can be used
+//! to put and extract them from streams of bytes:
 //!
 //! ```
 //! use las::point::Format;