Apply suggestions that make doc take the plural form

Co-authored-by: Georg Brandl <georg@python.org>
Co-authored-by: David Hewitt <1939362+davidhewitt@users.noreply.github.com>

src/buffer.rs

@@ -71,7 +71,7 @@ pub enum ElementType {
 }
 
 impl ElementType {
-    /// Determine the `ElementType` from a Python `struct` module format string.
+    /// Determines the `ElementType` from a Python `struct` module format string.
     pub fn from_format(format: &CStr) -> ElementType {
         match format.to_bytes() {
             [char] | [b'@', char] => native_element_type_from_type_char(*char),
@@ -606,13 +606,13 @@ impl<T> Drop for PyBuffer<T> {
 pub struct ReadOnlyCell<T: Element>(cell::UnsafeCell<T>);
 
 impl<T: Element> ReadOnlyCell<T> {
-    /// Obtain a copy of the current content.
+    /// Returns a copy of the current value.
     #[inline]
     pub fn get(&self) -> T {
         unsafe { *self.0.get() }
     }
 
-    /// Get a pointer to the current content.
+    /// Returns a pointer to the current value.
     #[inline]
     pub fn as_ptr(&self) -> *const T {
         self.0.get()

src/exceptions.rs

@@ -18,7 +18,7 @@ macro_rules! impl_exception_boilerplate {
         }
 
         impl $name {
-            /// Create a new [PyErr](crate::PyErr) of this type.
+            /// Creates a new [PyErr](crate::PyErr) of this type.
             pub fn new_err<A>(args: A) -> $crate::PyErr
             where
                 A: $crate::PyErrArguments + Send + Sync + 'static,
@@ -276,7 +276,7 @@ impl_native_exception!(PyIOError, PyExc_IOError);
 impl_native_exception!(PyWindowsError, PyExc_WindowsError);
 
 impl PyUnicodeDecodeError {
-    /// Create a Python `UnicodeDecodeError`.
+    /// Creates a Python `UnicodeDecodeError`.
     pub fn new<'p>(
         py: Python<'p>,
         encoding: &CStr,
@@ -296,7 +296,7 @@ impl PyUnicodeDecodeError {
         }
     }
 
-    /// Create a Python `UnicodeDecodeError` from a Rust UTF-8 decoding error.
+    /// Creates a Python `UnicodeDecodeError` from a Rust UTF-8 decoding error.
     pub fn new_utf8<'p>(
         py: Python<'p>,
         input: &[u8],

src/ffi/mod.rs

@@ -5,7 +5,7 @@
 //! need to interact with this module at all.
 //!
 //! The contents of this module are not documented here, as it would entail
-//! keeping the documentation up to date. Consult the [Python/C API Reference
+//! basically copying the documentation from CPython. Consult the [Python/C API Reference
 //! Manual][capi] for up-to-date documentation.
 //!
 //! # Safety

src/instance.rs

@@ -18,7 +18,7 @@ use std::ptr::NonNull;
 /// to the GIL, which is why you can get a token from all references of those
 /// types.
 pub unsafe trait PyNativeType: Sized {
-    /// Implicitly acquire the GIL marker.
+    /// Returns a GIL marker constrained to the lifetime of this type.
     fn py(&self) -> Python {
         unsafe { Python::assume_gil_acquired() }
     }

src/pyclass_slots.rs

@@ -6,9 +6,9 @@ use crate::{ffi, Python};
 pub trait PyClassDict {
     /// Whether this `__dict__` field is capable of holding a dictionary.
     const IS_DUMMY: bool = true;
-    /// Initialise a [PyObject](crate::ffi::PyObject) `__dict__` reference.
+    /// Initializes a [PyObject](crate::ffi::PyObject) `__dict__` reference.
     fn new() -> Self;
-    /// Empty the dictionary of its key-value pairs.
+    /// Empties the dictionary of its key-value pairs.
     #[inline]
     fn clear_dict(&mut self, _py: Python) {}
     private_decl! {}
@@ -18,9 +18,9 @@ pub trait PyClassDict {
 pub trait PyClassWeakRef {
     /// Whether this `weakref` type is capable of holding weak references.
     const IS_DUMMY: bool = true;
-    /// Initialize a `weakref` instance.
+    /// Initializes a `weakref` instance.
     fn new() -> Self;
-    /// Clear the weak references to the given object.
+    /// Clears the weak references to the given object.
     ///
     /// # Safety
     /// - `_obj` must be a pointer to the pyclass instance which contains `self`.

src/types/datetime.rs

@@ -33,17 +33,17 @@ use std::ptr;
 
 /// Trait for accessing the date components of a struct containing a date.
 pub trait PyDateAccess {
-    /// Return the year, as a positive int.
+    /// Returns the year, as a positive int.
     ///
     /// Implementations should conform to the upstream documentation:
     /// <https://docs.python.org/3/c-api/datetime.html#c.PyDateTime_GET_YEAR>
     fn get_year(&self) -> i32;
-    /// Return the month, as an int from 1 through 12.
+    /// Returns the month, as an int from 1 through 12.
     ///
     /// Implementations should conform to the upstream documentation:
     /// <https://docs.python.org/3/c-api/datetime.html#c.PyDateTime_GET_MONTH>
     fn get_month(&self) -> u8;
-    /// Return the day, as an int from 1 through 31.
+    /// Returns the day, as an int from 1 through 31.
     ///
     /// Implementations should conform to the upstream documentation:
     /// <https://docs.python.org/3/c-api/datetime.html#c.PyDateTime_GET_DAY>
@@ -56,17 +56,17 @@ pub trait PyDateAccess {
 /// microsecond) representation of the delta, they are *not* intended as
 /// aliases for calculating the total duration in each of these units.
 pub trait PyDeltaAccess {
-    /// Return the number of days, as an int from -999999999 to 999999999.
+    /// Returns the number of days, as an int from -999999999 to 999999999.
     ///
     /// Implementations should conform to the upstream documentation:
     /// <https://docs.python.org/3/c-api/datetime.html#c.PyDateTime_DELTA_GET_DAYS>
     fn get_days(&self) -> i32;
-    /// Return the number of seconds, as an int from 0 through 86399.
+    /// Returns the number of seconds, as an int from 0 through 86399.
     ///
     /// Implementations should conform to the upstream documentation:
     /// <https://docs.python.org/3/c-api/datetime.html#c.PyDateTime_DELTA_GET_DAYS>
     fn get_seconds(&self) -> i32;
-    /// Return the number of microseconds, as an int from 0 through 999999.
+    /// Returns the number of microseconds, as an int from 0 through 999999.
     ///
     /// Implementations should conform to the upstream documentation:
     /// <https://docs.python.org/3/c-api/datetime.html#c.PyDateTime_DELTA_GET_DAYS>
@@ -75,27 +75,27 @@ pub trait PyDeltaAccess {
 
 /// Trait for accessing the time components of a struct containing a time.
 pub trait PyTimeAccess {
-    /// Return the hour, as an int from 0 through 23.
+    /// Returns the hour, as an int from 0 through 23.
     ///
     /// Implementations should conform to the upstream documentation:
     /// <https://docs.python.org/3/c-api/datetime.html#c.PyDateTime_DATE_GET_HOUR>
     fn get_hour(&self) -> u8;
-    /// Return the minute, as an int from 0 through 59.
+    /// Returns the minute, as an int from 0 through 59.
     ///
     /// Implementations should conform to the upstream documentation:
     /// <https://docs.python.org/3/c-api/datetime.html#c.PyDateTime_DATE_GET_MINUTE>
     fn get_minute(&self) -> u8;
-    /// Return the second, as an int from 0 through 59.
+    /// Returns the second, as an int from 0 through 59.
     ///
     /// Implementations should conform to the upstream documentation:
     /// <https://docs.python.org/3/c-api/datetime.html#c.PyDateTime_DATE_GET_SECOND>
     fn get_second(&self) -> u8;
-    /// Return the microsecond, as an int from 0 through 999999.
+    /// Returns the microsecond, as an int from 0 through 999999.
     ///
     /// Implementations should conform to the upstream documentation:
     /// <https://docs.python.org/3/c-api/datetime.html#c.PyDateTime_DATE_GET_MICROSECOND>
     fn get_microsecond(&self) -> u32;
-    /// Return whether this date is the later of two moments with the
+    /// Returns whether this date is the later of two moments with the
     /// same representation, during a repeated interval.
     ///
     /// This typically occurs at the end of daylight savings time, or during
@@ -117,7 +117,7 @@ pyobject_native_type!(
 );
 
 impl PyDate {
-    /// Create a new `datetime.date`.
+    /// Creates a new `datetime.date`.
     pub fn new(py: Python, year: i32, month: u8, day: u8) -> PyResult<&PyDate> {
         unsafe {
             let ptr = (PyDateTimeAPI.Date_FromDate)(
@@ -320,7 +320,7 @@ pyobject_native_type!(
 );
 
 impl PyTime {
-    /// Create a new `datetime.time` object.
+    /// Creates a new `datetime.time` object.
     pub fn new<'p>(
         py: Python<'p>,
         hour: u8,
@@ -416,7 +416,7 @@ pyobject_native_type!(
 );
 
 impl PyDelta {
-    /// Create a new `timedelta`.
+    /// Creates a new `timedelta`.
     pub fn new(
         py: Python,
         days: i32,

src/types/sequence.rs

@@ -28,7 +28,7 @@ impl PySequence {
         }
     }
 
-    /// Whether the sequence is empty.
+    /// Returns whether the sequence is empty.
     #[inline]
     pub fn is_empty(&self) -> PyResult<bool> {
         self.len().map(|l| l == 0)

src/types/string.rs

@@ -27,7 +27,9 @@ impl PyString {
         unsafe { py.from_owned_ptr(ffi::PyUnicode_FromStringAndSize(ptr, len)) }
     }
 
-    /// Attempt to create a Python string from a Python bytes-like object.
+    /// Attempts to create a Python string from a Python [bytes-like object].
+    ///
+    /// [bytes-like object]: (https://docs.python.org/3/glossary.html#term-bytes-like-object).
     pub fn from_object<'p>(src: &'p PyAny, encoding: &str, errors: &str) -> PyResult<&'p PyString> {
         unsafe {
             src.py()