Merge pull request #313 from PyO3/deny-missing-docs

Consolidate deny-missing-docs and missing-debug-implementations lints.

Author: adamreichold

src/array.rs

@@ -23,7 +23,10 @@ use crate::borrow::{PyReadonlyArray, PyReadwriteArray};
 use crate::cold;
 use crate::convert::{ArrayExt, IntoPyArray, NpyIndex, ToNpyDims, ToPyArray};
 use crate::dtype::{Element, PyArrayDescr};
-use crate::error::{BorrowError, DimensionalityError, FromVecError, NotContiguousError, TypeError};
+use crate::error::{
+    BorrowError, DimensionalityError, FromVecError, NotContiguousError, TypeError,
+    DIMENSIONALITY_MISMATCH_ERR, MAX_DIMENSIONALITY_ERR,
+};
 use crate::npyffi::{self, npy_intp, NPY_ORDER, PY_ARRAY_API};
 use crate::slice_container::PySliceContainer;
 
@@ -358,7 +361,7 @@ impl<T: Element, D: Dimension> PyArray<T, D> {
     /// Same as [shape](#method.shape), but returns `D`
     #[inline(always)]
     pub fn dims(&self) -> D {
-        D::from_dimension(&Dim(self.shape())).expect("mismatching dimensions")
+        D::from_dimension(&Dim(self.shape())).expect(DIMENSIONALITY_MISMATCH_ERR)
     }
 
     /// Creates a new uninitialized PyArray in python heap.
@@ -838,12 +841,9 @@ impl<T: Element, D: Dimension> PyArray<T, D> {
             itemsize: usize,
             mut data_ptr: *mut u8,
         ) -> (StrideShape<D>, u32, *mut u8) {
-            let shape = D::from_dimension(&Dim(shape)).expect("mismatching dimensions");
+            let shape = D::from_dimension(&Dim(shape)).expect(DIMENSIONALITY_MISMATCH_ERR);
 
-            assert!(
-                strides.len() <= 32,
-                "Only dimensionalities of up to 32 are supported"
-            );
+            assert!(strides.len() <= 32, "{}", MAX_DIMENSIONALITY_ERR);
 
             let mut new_strides = D::zeros(strides.len());
             let mut inverted_axes = 0_u32;

src/borrow.rs

@@ -159,7 +159,6 @@
 //! More involved cases like the example from above may be supported in the future.
 //!
 //! [base]: https://numpy.org/doc/stable/reference/c-api/types-and-structures.html#c.NPY_AO.base
-#![deny(missing_docs)]
 
 use std::any::type_name;
 use std::cell::UnsafeCell;

src/convert.rs

@@ -1,5 +1,4 @@
 //! Defines conversion traits between Rust types and NumPy data types.
-#![deny(missing_docs)]
 
 use std::{mem, os::raw::c_int, ptr};
 
@@ -8,6 +7,7 @@ use pyo3::Python;
 
 use crate::array::PyArray;
 use crate::dtype::Element;
+use crate::error::MAX_DIMENSIONALITY_ERR;
 use crate::npyffi::{self, npy_intp};
 use crate::sealed::Sealed;
 
@@ -184,10 +184,7 @@ where
         let strides = self.strides();
         let itemsize = mem::size_of::<A>() as isize;
 
-        assert!(
-            strides.len() <= 32,
-            "Only dimensionalities of up to 32 are supported"
-        );
+        assert!(strides.len() <= 32, "{}", MAX_DIMENSIONALITY_ERR);
 
         let mut new_strides = [0; 32];
 

src/error.rs

@@ -7,6 +7,13 @@ use pyo3::{exceptions::PyTypeError, PyErr, PyErrArguments, PyObject, Python, ToP
 
 use crate::dtype::PyArrayDescr;
 
+/// Array dimensionality should be limited by [`NPY_MAXDIMS`][NPY_MAXDIMS] which is currently 32.´
+///
+/// [NPY_MAXDIMS]: https://github.com/numpy/numpy/blob/4c60b3263ac50e5e72f6a909e156314fc3c9cba0/numpy/core/include/numpy/ndarraytypes.h#L40
+pub(crate) const MAX_DIMENSIONALITY_ERR: &str = "unexpected dimensionality: NumPy is expected to limit arrays to 32 or fewer dimensions.\nPlease report a bug against the `rust-numpy` crate.";
+
+pub(crate) const DIMENSIONALITY_MISMATCH_ERR: &str = "inconsistent dimensionalities: The dimensionality expected by `PyArray` does not match that given by NumPy.\nPlease report a bug against the `rust-numpy` crate.";
+
 macro_rules! impl_pyerr {
     ($err_type:ty) => {
         impl Error for $err_type {}
@@ -120,7 +127,9 @@ impl_pyerr!(NotContiguousError);
 #[derive(Debug)]
 #[non_exhaustive]
 pub enum BorrowError {
+    /// The given array is already borrowed
     AlreadyBorrowed,
+    /// The given array is not writeable
     NotWriteable,
 }
 

src/lib.rs

@@ -32,6 +32,7 @@
 //! [c-api]: https://numpy.org/doc/stable/reference/c-api
 //! [ndarray]: https://numpy.org/doc/stable/reference/arrays.ndarray.html
 
+#![deny(missing_docs, missing_debug_implementations)]
 // We often want to make the GIL lifetime explicit.
 #![allow(clippy::needless_lifetimes)]
 

src/npyffi/mod.rs

@@ -3,6 +3,8 @@
 //! <https://numpy.org/doc/stable/reference/c-api>
 #![allow(
     non_camel_case_types,
+    missing_docs,
+    missing_debug_implementations,
     clippy::too_many_arguments,
     clippy::missing_safety_doc
 )]

src/npyiter.rs

@@ -16,6 +16,7 @@
 #![deprecated(
     note = "The wrappers of the array iterator API are deprecated, please use ndarray's iterators like `Lanes` and `Zip` instead."
 )]
+#![allow(missing_debug_implementations)]
 
 use std::marker::PhantomData;
 use std::os::raw::{c_char, c_int};
@@ -48,15 +49,25 @@ use crate::sealed::Sealed;
 /// [iterator]: https://numpy.org/doc/stable/reference/c-api/iterator.html#c.NpyIter_MultiNew
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 pub enum NpyIterFlag {
+    /// [`NPY_ITER_COMMON_DTYPE`](https://numpy.org/doc/stable/reference/c-api/iterator.html#c.NPY_ITER_COMMON_DTYPE)
     CommonDtype,
+    /// [`NPY_ITER_REFS_OK`](https://numpy.org/doc/stable/reference/c-api/iterator.html#c.NPY_ITER_REFS_OK)
     RefsOk,
+    /// [`NPY_ITER_ZEROSIZE_OK`](https://numpy.org/doc/stable/reference/c-api/iterator.html#c.NPY_ITER_ZEROSIZE_OK)
     ZerosizeOk,
+    /// [`NPY_ITER_REDUCE_OK`](https://numpy.org/doc/stable/reference/c-api/iterator.html#c.NPY_ITER_REDUCE_OK)
     ReduceOk,
+    /// [`NPY_ITER_RANGED`](https://numpy.org/doc/stable/reference/c-api/iterator.html#c.NPY_ITER_RANGED)
     Ranged,
+    /// [`NPY_ITER_BUFFERED`](https://numpy.org/doc/stable/reference/c-api/iterator.html#c.NPY_ITER_BUFFERED)
     Buffered,
+    /// [`NPY_ITER_GROWINNER`](https://numpy.org/doc/stable/reference/c-api/iterator.html#c.NPY_ITER_GROWINNER)
     GrowInner,
+    /// [`NPY_ITER_DELAY_BUFALLOC`](https://numpy.org/doc/stable/reference/c-api/iterator.html#c.NPY_ITER_DELAY_BUFALLOC)
     DelayBufAlloc,
+    /// [`NPY_ITER_DONT_NEGATE_STRIDES`](https://numpy.org/doc/stable/reference/c-api/iterator.html#c.NPY_ITER_DONT_NEGATE_STRIDES)
     DontNegateStrides,
+    /// [`NPY_ITER_COPY_IF_OVERLAP`](https://numpy.org/doc/stable/reference/c-api/iterator.html#c.NPY_ITER_COPY_IF_OVERLAP)
     CopyIfOverlap,
     // CIndex,
     // FIndex,
@@ -91,8 +102,11 @@ mod itermode {
 
     /// A combinator type that represents the mode of an iterator.
     pub trait MultiIterMode: Sealed {
+        #[doc(hidden)]
         type Pre: MultiIterMode;
+        #[doc(hidden)]
         const FLAG: npy_uint32 = 0;
+        #[doc(hidden)]
         fn flags() -> Vec<npy_uint32> {
             if Self::FLAG == 0 {
                 Vec::new()