Add documentation to types/datetime.rs

This adds some light doc comments to the safe rust bindings.

src/ffi/datetime.rs

@@ -1,9 +1,9 @@
 #![cfg_attr(feature="cargo-clippy", allow(type_complexity))]
-/// FFI bindings to the functions and structs defined in `datetime.h`
-///
-/// This is the unsafe thin  wrapper around the [CPython C API](https://docs.python.org/3/c-api/datetime.html),
-/// and covers the various date and time related objects in the Python `datetime`
-/// standard library module.
+//! FFI bindings to the functions and structs defined in `datetime.h`
+//!
+//! This is the unsafe thin  wrapper around the [CPython C API](https://docs.python.org/3/c-api/datetime.html),
+//! and covers the various date and time related objects in the Python `datetime`
+//! standard library module.
 use ffi::PyCapsule_Import;
 use ffi::Py_hash_t;
 use ffi::{PyObject, PyTypeObject};
@@ -105,8 +105,8 @@ const _PyDateTime_DATETIME_DATASIZE: usize = 10;
 
 #[repr(C)]
 #[derive(Debug, Copy, Clone)]
+/// Structure representing a `datetime.date`
 pub struct PyDateTime_Date {
-    /// Structure representing a `datetime.date`
     pub ob_base: PyObject,
     pub hashcode: Py_hash_t,
     pub hastzinfo: c_char,
@@ -115,8 +115,8 @@ pub struct PyDateTime_Date {
 
 #[repr(C)]
 #[derive(Debug, Copy, Clone)]
+/// Structure representing a `datetime.time`
 pub struct PyDateTime_Time {
-    /// Structure representing a `datetime.time`
     pub ob_base: PyObject,
     pub hashcode: Py_hash_t,
     pub hastzinfo: c_char,
@@ -128,8 +128,8 @@ pub struct PyDateTime_Time {
 
 #[repr(C)]
 #[derive(Debug, Copy, Clone)]
+/// Structure representing a `datetime.datetime`
 pub struct PyDateTime_DateTime {
-    /// Structure representing a `datetime.datetime`
     pub ob_base: PyObject,
     pub hashcode: Py_hash_t,
     pub hastzinfo: c_char,
@@ -141,8 +141,8 @@ pub struct PyDateTime_DateTime {
 
 #[repr(C)]
 #[derive(Debug, Copy, Clone)]
+/// Structure representing a `datetime.timedelta`
 pub struct PyDateTime_Delta {
-    /// Structure representing a `datetime.timedelta`
     pub ob_base: PyObject,
     pub hashcode: Py_hash_t,
     pub days: c_int,

src/types/datetime.rs

@@ -1,3 +1,7 @@
+//! Safe Rust wrappers for types defined in the Python `datetime` library
+//!
+//! For more details about these types, see the [Python
+//! documentation](https://docs.python.org/3/library/datetime.html)
 use conversion::ToPyObject;
 use err::PyResult;
 use ffi;
@@ -28,19 +32,27 @@ use std::os::raw::c_int;
 use std::ptr;
 use types::PyTuple;
 
-// Traits
+/// Access traits
+
+/// Trait for accessing the date components of a struct containing a date.
 pub trait PyDateAccess {
     fn get_year(&self) -> i32;
     fn get_month(&self) -> u8;
     fn get_day(&self) -> u8;
 }
 
+/// Trait for accessing the components of a struct containing a timedelta.
+///
+/// Note: These access the individual components of a (day, second,
+/// microsecond) representation of the delta, they are *not* intended as
+/// aliases for calculating the total duration in each of these units.
 pub trait PyDeltaAccess {
     fn get_days(&self) -> i32;
     fn get_seconds(&self) -> i32;
     fn get_microseconds(&self) -> i32;
 }
 
+/// Trait for accessing the time components of a struct containing a time.
 pub trait PyTimeAccess {
     fn get_hour(&self) -> u8;
     fn get_minute(&self) -> u8;
@@ -50,7 +62,7 @@ pub trait PyTimeAccess {
     fn get_fold(&self) -> u8;
 }
 
-// datetime.date bindings
+/// Bindings around `datetime.date`
 pub struct PyDate(PyObject);
 pyobject_native_type!(PyDate, PyDateTime_DateType, PyDate_Check);
 
@@ -67,6 +79,9 @@ impl PyDate {
         }
     }
 
+    /// Construct a `datetime.date` from a POSIX timestamp
+    ///
+    /// This is equivalent to `datetime.date.fromtimestamp`
     pub fn from_timestamp(py: Python, timestamp: i64) -> PyResult<Py<PyDate>> {
         let args = PyTuple::new(py, &[timestamp]);
 
@@ -91,7 +106,7 @@ impl PyDateAccess for PyDate {
     }
 }
 
-// datetime.datetime bindings
+/// Bindings for `datetime.datetime`
 pub struct PyDateTime(PyObject);
 pyobject_native_type!(PyDateTime, PyDateTime_DateTimeType, PyDateTime_Check);
 
@@ -123,6 +138,9 @@ impl PyDateTime {
         }
     }
 
+    /// Construct a `datetime` object from a POSIX timestamp
+    ///
+    /// This is equivalent to `datetime.datetime.from_timestamp`
     pub fn from_timestamp(
         py: Python,
         timestamp: f64,
@@ -185,7 +203,7 @@ impl PyTimeAccess for PyDateTime {
     }
 }
 
-// datetime.time
+/// Bindings for `datetime.time`
 pub struct PyTime(PyObject);
 pyobject_native_type!(PyTime, PyDateTime_TimeType, PyTime_Check);
 
@@ -212,6 +230,9 @@ impl PyTime {
     }
 
     #[cfg(Py_3_6)]
+    /// Alternate constructor that takes a `fold` argument
+    ///
+    /// First available in Python 3.6.
     pub fn new_with_fold(
         py: Python,
         hour: u8,
@@ -259,11 +280,13 @@ impl PyTimeAccess for PyTime {
     }
 }
 
-// datetime.tzinfo bindings
+/// Bindings for `datetime.tzinfo`
+///
+/// This is an abstract base class and should not be constructed directly.
 pub struct PyTzInfo(PyObject);
 pyobject_native_type!(PyTzInfo, PyDateTime_TZInfoType, PyTZInfo_Check);
 
-// datetime.timedelta bindings
+/// Bindings for `datetime.timedelta`
 pub struct PyDelta(PyObject);
 pyobject_native_type!(PyDelta, PyDateTime_DeltaType, PyDelta_Check);