add more docs

programmerjake · programmerjake · commit 4c20f7179f3d · 2019-12-09T19:01:34.000-08:00
diff --git a/Cargo.toml b/Cargo.toml
@@ -8,6 +8,7 @@ edition = "2018"
 license = "LGPL-2.1-or-later"
 description = "soft-float library that intends to be a straightforward reference implementation of IEEE 754"
 readme = "README.md"
+repository = "https://salsa.debian.org/Kazan-team/simple-soft-float"
 
 [lib]
 name = "simple_soft_float"
diff --git a/README.md b/README.md
@@ -1 +1,57 @@
-Soft-float library that intends to be a straightforward reference implementation of IEEE 754
+Soft-float library that intends to be a straightforward reference implementation of IEEE 754.
+
+## Installation for use from Rust
+
+Add to your `Cargo.toml`:
+
+```toml
+[dependencies.simple-soft-float]
+# switch to crates.io version once new version is published
+git = "https://salsa.debian.org/Kazan-team/simple-soft-float"
+rev = "<current git revision>"
+```
+
+## Installation for use from Python
+
+Install Rust using [rustup.rs](https://rustup.rs).
+
+Create CPython 3.6 to 3.7 virtualenv (not sure if 3.8 is supported yet).
+
+Install Python bindings build tool:
+```bash
+pip install maturin
+```
+
+Get source:
+```bash
+git clone https://salsa.debian.org/Kazan-team/simple-soft-float.git
+cd simple-soft-float
+```
+
+Change source dir to use specific version of Rust nightly:
+(must be in `simple-soft-float` dir):
+```bash
+rustup override set nightly-2019-07-19
+```
+
+Build and Test (like `setup.py develop`):
+```bash
+cargo test --features python # runs tests from Rust
+# build and install to python
+maturin develop --cargo-extra-args="--features python-extension"
+python -m unittest # runs smoke tests from Python
+```
+
+Build Rust docs:
+```bash
+cargo doc --features python # ignore warning about rand_core name collision
+open docs in default browser:
+xdg-open target/doc/simple_soft_float/struct.DynamicFloat.html
+```
+
+Build Python docs:
+```bash
+pip install pdoc3
+pdoc3 simple_soft_float --html -o target/python-docs
+xdg-open target/python-docs/simple_soft_float.html
+```
diff --git a/src/lib.rs b/src/lib.rs
@@ -61,7 +61,9 @@ python_enum! {
     #[pyenum(module = simple_soft_float, repr = u8, test_fn = test_sign_enum)]
     /// sign of floating-point number
     pub enum Sign {
+        /// + sign
         Positive = 0,
+        /// - sign
         Negative = 1,
     }
 }
@@ -167,6 +169,7 @@ impl Default for RoundingMode {
 }
 
 bitflags! {
+    /// IEEE 754 status flags
     pub struct StatusFlags: u32 {
         const INVALID_OPERATION = 0b00001;
         const DIVISION_BY_ZERO = 0b00010;
@@ -184,6 +187,21 @@ impl Default for StatusFlags {
 
 python_enum! {
     #[pyenum(module = simple_soft_float, repr = u8, test_fn = test_exception_handling_mode_enum)]
+    /// Select if the underflow exception should be signaled when the result is exact.
+    ///
+    /// In IEEE 754, when exceptions are set to use the default handlers
+    /// (they are ignored -- the default for most programming languages), then
+    /// underflow exceptions are only signalled when the result is not exact.
+    ///
+    /// When exceptions are instead set to trap, then underflow exceptions are
+    /// signalled even when the result is exact, to allow the exception handler
+    /// to emulate flush-to-zero FP semantics.
+    ///
+    /// Since simple-soft-float doesn't support trapping exceptions, to simulate
+    /// trapping exceptions, use `DefaultSignalExactUnderflow` as the exception
+    /// handling mode and check `status_flags` after every operation.
+    ///
+    /// Otherwise, use the default value of `DefaultIgnoreExactUnderflow`.
     pub enum ExceptionHandlingMode {
         DefaultIgnoreExactUnderflow,
         DefaultSignalExactUnderflow,
@@ -198,6 +216,7 @@ impl Default for ExceptionHandlingMode {
 
 python_enum! {
     #[pyenum(module = simple_soft_float, repr = u8, test_fn = test_tininess_detection_mode_enum)]
+    /// IEEE 754 tininess detection mode
     pub enum TininessDetectionMode {
         AfterRounding,
         BeforeRounding,
@@ -212,6 +231,7 @@ impl Default for TininessDetectionMode {
 
 python_enum! {
     #[pyenum(module = simple_soft_float, repr = u8, test_fn = test_binary_nan_propagation_mode_enum)]
+    /// Select how NaN payloads should be propagated
     pub enum BinaryNaNPropagationMode {
         AlwaysCanonical,
         FirstSecond,
@@ -223,6 +243,7 @@ python_enum! {
 
 python_enum! {
     #[pyenum(module = simple_soft_float, repr = u8, test_fn = test_unary_nan_propagation_mode_enum)]
+    /// Select how NaN payloads should be propagated
     pub enum UnaryNaNPropagationMode {
         AlwaysCanonical,
         First,
@@ -377,6 +398,7 @@ impl Default for TernaryNaNPropagationResults {
 
 python_enum! {
     #[pyenum(module = simple_soft_float, repr = u8, test_fn = test_ternary_nan_propagation_mode_enum)]
+    /// Select how NaN payloads should be propagated
     pub enum TernaryNaNPropagationMode {
         AlwaysCanonical,
         FirstSecondThird,
@@ -586,6 +608,7 @@ impl TernaryNaNPropagationMode {
 
 python_enum! {
     #[pyenum(module = simple_soft_float, repr = u8, test_fn = test_fma_inf_zero_qnan_result_enum)]
+    /// select the result of fused `Infinity * 0.0 + QNaN` and `0.0 * Infinity + QNaN`
     pub enum FMAInfZeroQNaNResult {
         FollowNaNPropagationMode,
         CanonicalAndGenerateInvalid,
@@ -601,6 +624,7 @@ impl Default for FMAInfZeroQNaNResult {
 
 python_enum! {
     #[pyenum(module = simple_soft_float, repr = u8, test_fn = test_float_to_float_conversion_nan_propagation_mode_enum)]
+    /// select how NaN payloads are propagated in float -> float conversions
     pub enum FloatToFloatConversionNaNPropagationMode {
         AlwaysCanonical,
         RetainMostSignificantBits,
@@ -636,6 +660,7 @@ impl From<FPStateMergeFailed> for PyErr {
 }
 
 impl FPState {
+    /// combine two `FPState` values into one, assigning the result to `self`
     pub fn checked_merge_assign(&mut self, rhs: Self) -> Result<(), FPStateMergeFailed> {
         let status_flags = self.status_flags | rhs.status_flags;
         let same = Self {
@@ -652,13 +677,16 @@ impl FPState {
             Err(FPStateMergeFailed)
         }
     }
+    /// combine two `FPState` values into one, assigning the result to `self`
     pub fn merge_assign(&mut self, rhs: Self) {
         self.checked_merge_assign(rhs).unwrap();
     }
+    /// combine two `FPState` values into one, returning the result
     pub fn checked_merge(mut self, rhs: Self) -> Result<Self, FPStateMergeFailed> {
         self.checked_merge_assign(rhs)?;
         Ok(self)
     }
+    /// combine two `FPState` values into one, returning the result
     pub fn merge(mut self, rhs: Self) -> Self {
         self.merge_assign(rhs);
         self
@@ -667,6 +695,7 @@ impl FPState {
 
 python_enum! {
     #[pyenum(module = simple_soft_float, repr = u8, test_fn = test_float_class_enum)]
+    /// float classification
     pub enum FloatClass {
         NegativeInfinity,
         NegativeNormal,
@@ -816,6 +845,12 @@ impl Neg for FloatClass {
 
 python_enum! {
     #[pyenum(module = simple_soft_float, repr = u8, test_fn = test_quiet_nan_format_enum)]
+    /// the format for quiet NaN values
+    ///
+    /// IEEE 754 states that implementations *should* use the MSB of the
+    /// mantissa being set to indicate a quiet NaN, however MIPS before
+    /// the 2008 revision and PA-RISC use the MSB of the mantissa being clear
+    /// to indicate a quiet NaN.
     pub enum QuietNaNFormat {
         /// MSB of mantissa set to indicate quiet NaN
         Standard,
@@ -1611,6 +1646,7 @@ impl RoundedMantissa {
 
 python_enum! {
     #[pyenum(module = simple_soft_float, repr = u8, test_fn = test_up_or_down_enum)]
+    /// select Up or Down
     pub enum UpOrDown {
         Up,
         Down,
diff --git a/src/python.rs b/src/python.rs
@@ -155,12 +155,19 @@ impl StatusFlags {
                     writeln!(src, "def f(status_flags_repr):")?;
                     writeln!(src, "    import enum")?;
                     writeln!(src, "    class {}(enum.Flag):", StatusFlags::NAME)?;
+                    writeln!(src, "        \"\"\"IEEE 754 status flags\"\"\"")?;
                     for &(name, value) in StatusFlags::MEMBERS {
                         writeln!(src, "        {} = {}", name, value.bits())?;
                     }
                     writeln!(src, "        __module__ = \"simple_soft_float\"")?;
+                    writeln!(src, "        __qualname__ = \"{}\"", StatusFlags::NAME)?;
                     writeln!(src, "        def __repr__(self):")?;
                     writeln!(src, "            return status_flags_repr(self)")?;
+                    writeln!(
+                        src,
+                        "        __repr__.__qualname__ = \"{}.__repr__\"",
+                        StatusFlags::NAME
+                    )?;
                     writeln!(src, "    return {}", StatusFlags::NAME)?;
                     writeln!(src, "{} = f(status_flags_repr)", StatusFlags::NAME)?;
                     Ok(src)
diff --git a/src/python_macros.rs b/src/python_macros.rs
@@ -18,6 +18,13 @@ use pyo3::PyNativeType;
 #[cfg(feature = "python")]
 use std::fmt::{self, Write as _};
 
+#[cfg(feature = "python")]
+pub(crate) struct PythonEnumMember<T: PythonEnum> {
+    pub(crate) name: &'static str,
+    pub(crate) value: T,
+    pub(crate) docs: Option<&'static str>,
+}
+
 #[cfg(feature = "python")]
 pub(crate) trait PythonEnum:
     Copy
@@ -29,8 +36,9 @@ pub(crate) trait PythonEnum:
     + crate::python::ToPythonRepr
 {
     const NAME: &'static str;
+    const DOCS: Option<&'static str>;
     const MODULE_NAME: &'static str;
-    const MEMBERS: &'static [(&'static str, Self)];
+    const MEMBERS: &'static [PythonEnumMember<Self>];
     type Repr: Copy + 'static + fmt::Display + for<'source> FromPyObject<'source> + IntoPy<PyObject>;
     fn to_repr(self) -> Self::Repr;
     fn from_repr(value: Self::Repr) -> Option<Self>;
@@ -44,8 +52,14 @@ pub(crate) trait PythonEnum:
                 let get_class_src = || -> Result<String, fmt::Error> {
                     let mut retval = String::new();
                     writeln!(retval, "class {}(enum.Enum):", Self::NAME)?;
-                    for &(name, value) in Self::MEMBERS {
+                    if let Some(docs) = Self::DOCS {
+                        writeln!(retval, "    {:?}", docs)?;
+                    }
+                    for &PythonEnumMember { name, value, docs } in Self::MEMBERS {
                         writeln!(retval, "    {} = {}", name, value.to_repr())?;
+                        if let Some(docs) = docs {
+                            writeln!(retval, "    {:?}", docs)?;
+                        }
                     }
                     writeln!(retval, "{}.__module__ = module_name", Self::NAME)?;
                     Ok(retval)
@@ -87,7 +101,7 @@ pub(crate) trait PythonEnum:
                 Self::NAME,
                 Self::MODULE_NAME
             );
-            for &(_, value) in Self::MEMBERS {
+            for &PythonEnumMember { value, .. } in Self::MEMBERS {
                 let object: PyObject = value.into_py(py);
                 assert_eq!(value, object.extract::<Self>(py)?);
             }
@@ -128,20 +142,40 @@ pub(crate) fn python_enum_extract_impl<T: PythonEnum>(object: &PyAny) -> PyResul
     )))
 }
 
+#[cfg(feature = "python")]
+macro_rules! docs_to_string {
+    (#[doc = $doc_first:literal] $(#[doc = $doc_rest:literal])*) => {
+        Some(concat!($doc_first $(, "\n", $doc_rest)*))
+    };
+    () => {
+        None
+    };
+}
+
 #[cfg(feature = "python")]
 macro_rules! python_enum_impl {
     (
         #[pyenum(module = $module:ident, repr = $repr_type:ident, test_fn = $test_fn:ident)]
-        $(#[$meta:meta])*
+        $(#[doc = $enum_doc:literal])*
         $vis:vis enum $enum_name:ident {
-            $($value_name:ident $(= $value_init:expr)*,)+
+            $(
+                $(#[doc = $value_doc:literal])*
+                $value_name:ident $(= $value_init:expr)*,
+            )+
         }
     ) => {
         impl $crate::python_macros::PythonEnum for $enum_name {
             const NAME: &'static str = stringify!($enum_name);
+            const DOCS: Option<&'static str> = docs_to_string!($(#[doc = $enum_doc])*);
             const MODULE_NAME: &'static str = stringify!($module);
-            const MEMBERS: &'static [(&'static str, Self)] = &[
-                $((stringify!($value_name), Self::$value_name),)+
+            const MEMBERS: &'static [$crate::python_macros::PythonEnumMember<Self>] = &[
+                $(
+                    $crate::python_macros::PythonEnumMember {
+                        name: stringify!($value_name),
+                        value: Self::$value_name,
+                        docs: docs_to_string!($(#[doc = $value_doc])*),
+                    },
+                )+
             ];
             type Repr = $repr_type;
             fn to_repr(self) -> Self::Repr {
@@ -203,29 +237,32 @@ macro_rules! python_enum_impl {
 macro_rules! python_enum {
     (
         #[pyenum(module = $module:ident, repr = $repr_type:ident, test_fn = $test_fn:ident)]
-        $(#[$meta:meta])*
+        $(#[doc = $enum_doc:literal])*
         $vis:vis enum $enum_name:ident {
             $(
-                $(#[doc $($value_doc:tt)*])*
+                $(#[doc = $value_doc:literal])*
                 $value_name:ident $(= $value_init:expr)*,
             )+
         }
     ) => {
-        $(#[$meta])*
+        $(#[doc = $enum_doc])*
         #[derive(Copy, Clone, Hash, Eq, PartialEq, Debug)]
         #[repr($repr_type)]
         $vis enum $enum_name {
             $(
-                $(#[doc $($value_doc)*])*
+                $(#[doc = $value_doc])*
                 $value_name $(= $value_init)*,
             )+
         }
 
         python_enum_impl! {
             #[pyenum(module = $module, repr = $repr_type, test_fn = $test_fn)]
-            $(#[$meta])*
+            $(#[doc = $enum_doc])*
             $vis enum $enum_name {
-                $($value_name $(= $value_init)*,)+
+                $(
+                    $(#[doc = $value_doc])*
+                    $value_name $(= $value_init)*,
+                )+
             }
         }
     };
