[#1] Improve Rust Docs

src/ids/dev_id.rs

@@ -1,7 +1,22 @@
-//! # `PEP-440` Developmental release identifier
-
 use serde::{Deserialize, Serialize};
 
+/// # `PEP-440` Developmental release identifier
+/// This identifier is used to mark a developmental release
+///
+/// Examples of versions that use this struct:
+/// - `1.0.dev456`
+/// - `1.0rc1.dev1`
+///
+/// ## Example Usage
+/// ```
+/// use pyver::ids::DevHead;
+///
+/// assert!(
+///     DevHead { dev_num: Some(0) }
+///     >
+///     DevHead { dev_num: None }
+/// );
+/// ```
 #[derive(Debug, Serialize, Deserialize, Eq, PartialEq, PartialOrd)]
 pub struct DevHead {
     pub dev_num: Option<u32>,

src/ids/mod.rs

@@ -1,5 +1,5 @@
 //! # Identifiers
-//! Importing
+//! Importing Example
 //! ```
 //! use pyver::ids::{PreHeader, PostHeader, PostHead, DevHead, ReleaseHeader};
 //! ```

src/ids/post_id.rs

@@ -2,16 +2,53 @@ use serde::{Deserialize, Serialize};
 use std::cmp::Ordering;
 
 /// # `PEP-440` Post-Release identifier
+/// This identifier is used to mark a Post Release/Revision Version
+///
+/// Examples of versions that use this struct:
+/// - `1.0.post456`
+/// - `1.0rev`
+///
+/// ## Example Usage
+/// ```
+/// use pyver::ids::PostHeader;
+/// use pyver::ids::PostHead;
+///
+/// assert!(
+///     PostHeader {
+///         post_head: Some(PostHead::Post),
+///         post_num: Some(0),
+///     } > PostHeader {
+///         post_head: Some(PostHead::Post),
+///         post_num: None,
+///     }
+/// );
+/// ```
 #[derive(Debug, Serialize, Deserialize, Eq, PartialEq)]
 pub struct PostHeader {
     pub post_head: Option<PostHead>,
     pub post_num: Option<u32>,
 }
 
 /// `PEP-440` Post-Release Identifier Keyword
+/// This is a helper enum to tack whether it's a Revision or
+/// a Post-Release
+///
+/// Examples of versions that use this enum:
+/// - `1.0.post456`
+/// - `1.0rev`
 #[derive(Debug, Serialize, Deserialize, Eq, PartialEq)]
 pub enum PostHead {
+    /// ```
+    /// use pyver::ids::PostHead;
+    ///
+    /// PostHead::Post;
+    /// ```
     Post,
+    /// ```
+    /// use pyver::ids::PostHead;
+    ///
+    /// PostHead::Rev;
+    /// ```
     Rev,
 }
 

src/ids/pre_id.rs

@@ -1,33 +1,33 @@
-//! # `PEP-440` Pre-Release identifier
-
 use serde::{Deserialize, Serialize};
 
+/// # `PEP-440` Pre-Release identifier
+/// This identifier is used to mark a Pre-Release version
 #[derive(Debug, Serialize, Deserialize, Eq, PartialEq, PartialOrd)]
 pub enum PreHeader {
     /// Present in versions like 1.1beta1 or 1.0b1 both are represented the same way
     /// ```
-    ///# use pyver::ids::PreHeader;
+    /// use pyver::ids::PreHeader;
     ///
     /// PreHeader::Beta(Some(1));
     /// ```
     Beta(Option<u32>),
     /// Present in versions like 1.0alpha2 or 1.0a2 both are represented the same way
     /// ```
-    ///# use pyver::ids::PreHeader;
+    /// use pyver::ids::PreHeader;
     ///
     /// PreHeader::Alpha(Some(2));
     /// ```
     Alpha(Option<u32>),
     /// Present in versions like 1.1pre3
     /// ```
-    ///# use pyver::ids::PreHeader;
+    /// use pyver::ids::PreHeader;
     ///
     /// PreHeader::Preview(Some(3));
     /// ```
     Preview(Option<u32>),
     /// Present in versions like 1.1-rc-4 or 1.1c-4
     /// ```
-    ///# use pyver::ids::PreHeader;
+    /// use pyver::ids::PreHeader;
     ///
     /// PreHeader::ReleaseCandidate(Some(4));
     /// ```

src/lib.rs

@@ -1,8 +1,37 @@
-//! # Handling of `PEP-440`
-//!
-//! This library implements Pythons Package versioning system.
-//! Read more at <https://peps.python.org/pep-0440/>
+/*!
+# Handling of `PEP-440`
+This library implements Pythons Package versioning system.
 
+Read more at <https://peps.python.org/pep-0440/>
+
+# Usage
+The `pyver` crate is available on [crates.io](https://crates.io/crates/pyver),
+you can include it in your project by adding the following to your `Cargo.toml`.
+```toml
+[dependencies]
+pyver = "0.1"
+```
+# Example
+The following example shows how to parse a package version and
+how to compare them
+```
+use pyver::PackageVersion;
+
+let a = PackageVersion::new("v1.0a2.dev456").unwrap();
+let b = PackageVersion::new("v1.1a2.dev457").unwrap();
+
+assert!(a < b);
+```
+
+If you want to verify single version strings do
+```
+use pyver::validate_440_version;
+
+assert!(
+    validate_440_version("1.0").is_ok()
+);
+```
+*/
 use anyhow::Result;
 use serde::{Deserialize, Serialize};
 use std::fmt;
@@ -13,16 +42,15 @@ extern crate derivative;
 mod validator;
 pub use validator::validate_440_version;
 
-/// Make Identifiers module available for lib user
+/// Identifiers (i.e. the components of a version string)
 pub mod ids;
 use ids::{DevHead, PostHead, PostHeader, PreHeader, ReleaseHeader};
 
 /// `PEP-440` Compliant versioning system
 ///
-/// This struct is sorted so that PartialOrd
-/// correctly interprets priority
-///
-/// Lower == More important
+//# This struct is sorted so that PartialOrd
+//# correctly interprets priority
+//# Lower == More important
 ///
 /// # Example Usage
 /// ```
@@ -32,37 +60,41 @@ use ids::{DevHead, PostHead, PostHeader, PreHeader, ReleaseHeader};
 #[derive(Derivative, Debug, Serialize, Deserialize)]
 #[derivative(PartialOrd, PartialEq)]
 pub struct PackageVersion {
+    /// ## Original String
+    /// Just holds the original string passed in when creating
+    /// the `PackageVersion` as some formating data is lost
+    /// when parsing the string
     #[derivative(PartialOrd = "ignore", PartialEq = "ignore")]
     pub original: String,
 
-    /// # `PEP-440` Local version identifier
+    /// ## `PEP-440` Local version identifier
     /// Local version sorting will have to be it's own issue
     /// since there are no limits to what a local version can be
     ///
     /// For those who can read regex here it is for the local version:
     /// `[a-z0-9]+(?:(?:[\-_.][a-z0-9]+)+)?`
     ///
     /// Here in Rulex:
-    /// ```ignore
+    /// ```toml
     ///  ['a'-'z' '0'-'9']+
     ///  ((["-" "_" "."] ['a'-'z' '0'-'9']+)+)?
     /// ```
     #[derivative(PartialOrd = "ignore", PartialEq = "ignore")]
     pub local: Option<String>,
 
-    /// # `PEP-440` Developmental release identifier
+    /// ## `PEP-440` Developmental release identifier
     pub dev: Option<DevHead>,
 
-    /// # `PEP-440` Post-Release identifier
+    /// ## `PEP-440` Post-Release identifier
     pub post: Option<PostHeader>,
 
-    /// # `PEP-440` Pre-Release identifier
+    /// ## `PEP-440` Pre-Release identifier
     pub pre: Option<PreHeader>,
 
-    /// # `PEP-440` Release number
+    /// ## `PEP-440` Release number
     pub release: ReleaseHeader,
 
-    /// # `PEP-440` Version-Epoch
+    /// ## `PEP-440` Version-Epoch
     pub epoch: Option<u32>,
 }
 

src/validator.rs

@@ -3,7 +3,7 @@ use lazy_static::lazy_static;
 use pomsky_macro::pomsky;
 use regex::Captures;
 
-/// Utility Function for Checking if a PEP-440 Version String is valid
+/// Utility Function for Checking if a `PEP-440` Version String is valid
 /// and getting it's groups
 ///
 /// # Example Usage