doc: Basic docs for forrustts-core (#255)

Author: molpopgen

forrustts-core/src/lib.rs

@@ -1,3 +1,9 @@
+//! Core types for [`forrustts`](https://docs.rs/forrustts)
+
+#![warn(missing_docs)]
+#![warn(rustdoc::broken_intra_doc_links)]
+#![cfg_attr(doc_cfg, feature(doc_cfg))]
+
 use thiserror::Error;
 
 mod position;
@@ -9,8 +15,21 @@ mod time;
 pub use position::Position;
 pub use time::Time;
 
+/// Error type
 #[derive(Error, Debug)]
 pub enum Error {
+    /// Invalid [`Position`]
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// if let Err(e) = forrustts_core::Position::try_from(-1) {
+    ///     assert!(matches!(e, forrustts_core::Error::PositionError(-1)));
+    /// }
+    /// # else {
+    /// #   panic!("should be an Err...");
+    /// # }
+    /// ```
     #[error("{0:?}")]
     PositionError(i64),
 }

forrustts-core/src/position.rs

@@ -4,6 +4,28 @@
 pub struct Position(i64);
 
 impl Position {
+    /// Create a new Position
+    ///
+    /// # Returns
+    ///
+    /// * `Some` if `position` is non-negative
+    /// * `None` otherwise
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let p = forrustts_core::Position::new(10).unwrap();
+    /// assert_eq!(p, 10); // can be compared to i64
+    /// # assert_eq!(10, p);
+    /// # assert!(p > 0);
+    /// # assert!(p != 0);
+    /// # assert!(p >= 10);
+    /// # assert!(p <= 10);
+    /// # assert!(0 < p);
+    /// let p2 = forrustts_core::Position::new(11).unwrap();
+    /// assert!(p < p2);
+    /// assert!(p != p2);
+    /// ```
     pub fn new(position: i64) -> Option<Self> {
         if position >= 0 {
             Some(Self(position))
@@ -12,6 +34,21 @@ impl Position {
         }
     }
 
+    /// Create a new position with a non-negative integer
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let p = forrustts_core::Position::new_valid(10);
+    /// ```
+    ///
+    /// # Panics
+    ///
+    /// Will panic if `position` < 0.
+    ///
+    /// ```should_panic
+    /// let p = forrustts_core::Position::new(-1).unwrap();
+    /// ```
     pub fn new_valid(position: i64) -> Self {
         Self::new(position).unwrap()
     }

forrustts-core/src/prelude.rs

@@ -1,2 +1,10 @@
+//! Core library prelude
+//!
+//! # Examples
+//!
+//! ```
+//! use forrustts_core::prelude::*;
+//! ```
+
 pub use crate::Position;
 pub use crate::Time;