Fix clippy lints and added some documentation

Tested by `cargo test` and `cargo clippy`

README.md

@@ -76,3 +76,13 @@ FFI bindings for [`imath`](https://github.com/creachadair/imath/).
 [Documentation for `reckoner` from `main` branch](https://declanvk.github.io/reckoner/reckoner/index.html)
 
 [Documentation for `creachadair-imath-sys` from `main` branch](https://declanvk.github.io/reckoner/creachadair_imath_sys/index.html)
+
+## Contributing
+
+Download the crate using the command
+
+```bash
+git clone --recurse-submodules https://github.com/declanvk/reckoner
+```
+
+so that you also get the submodule sources, which are required to compile the `creachadair-imath-sys` crate. If you already cloned the project and forgot `--recurse-submodules`, you can combine the `git submodule init` and `git submodule update` steps by running `git submodule update --init`.

src/integer.rs

@@ -306,6 +306,8 @@ impl Integer {
     /// assert_eq!(a, 20);
     /// assert_eq!(b, 20, "Failed to copy");
     /// ```
+    #[allow(clippy::needless_pass_by_ref_mut)] // we allow this because we're signalling to the caller that we're going to
+                                               // mutate `other`
     pub fn copy_to(&self, other: &mut Self) {
         let self_raw = self.as_raw();
         let other_raw = other.as_raw();

src/integer/comparison.rs

@@ -102,7 +102,14 @@ macro_rules! impl_partial_ord {
     };
 }
 
-impl_partial_ord!(Integer, Integer::compare);
+// impl_partial_ord!(Integer, Integer::compare);
+// manual impl to satify clippy::incorrect_partial_ord_impl_on_ord_type lint
+impl PartialOrd for Integer {
+    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
+        Some(self.cmp(other))
+    }
+}
+
 impl_partial_ord!(u8, Integer::compare_c_long, deref rhs);
 impl_partial_ord!(i8, Integer::compare_c_long, deref rhs);
 impl_partial_ord!(u16, Integer::compare_c_long, deref rhs);

src/rational.rs

@@ -372,6 +372,8 @@ impl Rational {
     /// assert_eq!(a, b);
     /// assert_eq!(b, (34256, 54587));
     /// ```
+    #[allow(clippy::needless_pass_by_ref_mut)] // we allow this because we're signalling to the caller that we're going to
+                                               // mutate `other`
     pub fn copy_to(&self, other: &mut Self) {
         let self_raw = self.as_raw();
         let other_raw = other.as_raw();

src/rational/comparisons.rs

@@ -94,7 +94,14 @@ macro_rules! impl_partial_ord {
     };
 }
 
-impl_partial_ord!(Rational, Rational::compare);
+// impl_partial_ord!(Rational, Rational::compare);
+// manual impl to satify clippy::incorrect_partial_ord_impl_on_ord_type lint
+impl PartialOrd for Rational {
+    fn partial_cmp(&self, other: &Rational) -> Option<Ordering> {
+        Some(self.cmp(other))
+    }
+}
+
 impl_partial_ord!(Integer, Rational::compare, into rhs);
 impl_partial_ord!(u8, Rational::compare, into rhs);
 impl_partial_ord!(i8, Rational::compare, into rhs);