doc: constants page final form

Author: james-d-mitchell

docs/source/data-structures/constants/index.rst

@@ -5,42 +5,59 @@
 
     The full license is in the file LICENSE, distributed with this software.
 
-.. currentmodule:: _libsemigroups_pybind11
+.. currentmodule:: libsemigroups_pybind11
 
 Constants
 =========
 
 This page describes some of the constants used in ``libsemigroups_pybind11``.
 
+Constant types
+--------------
 
-.. autodata:: UNDEFINED
+.. autoclass:: LimitMax
 
-    This variable is used to indicate that a value is undefined.
-    :any:`UNDEFINED` is comparable with any integral value (signed or
-    unsigned) or constant via ``==`` and ``!=`` but not via ``<`` or ``>``.
+.. autoclass:: NegativeInfinity
 
+.. autoclass:: PositiveInfinity
 
-.. autodata:: POSITIVE_INFINITY
+.. autoclass:: Undefined
 
-    This variable of type :class:`_libsemigroups_pybind11.PositiveInfinity`
-    represents :math:`\infty`. :any:`POSITIVE_INFINITY` is comparable via
-    ``==``, ``!=``, ``<``, ``>`` with any integral value (signed or
-    unsigned) and with :any:`NEGATIVE_INFINITY`, and is comparable to any
-    other constant via ``==`` and ``!=``, but not by ``<`` and ``>``.
+Constant values
+---------------
 
+.. py:data:: LIMIT_MAX
 
-.. autodata:: LIMIT_MAX
+    This value represents the maximum value that certain function parameters
+    can have. This value has type :any:`LimitMax`.
 
-    This variable represents the maximum value that certain function
-    parameters can have. :any:`LIMIT_MAX` is comparable via ``==``, ``!=``,
-    ``<``, ``>`` with any integral value (signed or unsigned), and is
-    comparable to any other constant via ``==`` and ``!=``, but not by ``<``
-    and ``>``.
+    :any:`LIMIT_MAX` is comparable via ``==``, ``!=``, ``<``, ``>``
+    with any integral value, and is comparable to any other constant via ``==``
+    and ``!=``, but not by ``<`` and ``>``.
 
+.. py:data:: NEGATIVE_INFINITY
+   :value: -∞
 
-.. autodata:: NEGATIVE_INFINITY
+    This value represents :math:`-\infty` and has type :any:`NegativeInfinity`.
 
-    This variable represents :math:`-\infty`. :any:`NEGATIVE_INFINITY` is
-    comparable via ``==``, ``!=``, ``<``, ``>`` with any signed integral
-    value and with :any:`POSITIVE_INFINITY`, and is comparable to any other
-    constant via ``==`` and ``!=``.
+    :any:`NEGATIVE_INFINITY` is comparable via ``==``, ``!=``, ``<``, ``>``
+    with any integer and with :any:`POSITIVE_INFINITY`, and is comparable to
+    any other constant via ``==`` and ``!=``.
+
+.. py:data:: POSITIVE_INFINITY
+   :value: +∞
+
+    This value represents :math:`+\infty` and has type :any:`PositiveInfinity`.
+
+    :any:`POSITIVE_INFINITY` is comparable via ``==``, ``!=``, ``<``, ``>``
+    with any integral and with :any:`NEGATIVE_INFINITY`, and is comparable to
+    any other constant via ``==`` and ``!=``, but not by ``<`` and ``>``.
+
+.. py:data:: UNDEFINED
+
+    This value is used to indicate that a value is undefined and is of type
+    :any:`Undefined`. 
+
+    This value is comparable with other constants via ``==`` and ``!=``, and to
+    itself by ``<`` and ``>`` but is not comparable to any other types using
+    ``<`` or ``>``.

src/constants.cpp

@@ -33,17 +33,23 @@ namespace libsemigroups {
     // Undefined
     ////////////////////////////////////////////////////////////////////////
 
-    py::class_<Undefined>(m, "Undefined")
+    py::class_<Undefined>(m, "Undefined", R"pbdoc(
+The type of :any:`UNDEFINED`.
+
+This class is the type of the constant value :any:`UNDEFINED`, and appears as
+such in type annotations in ``libsemigroups_pybind11``.
+)pbdoc")
         .def("__repr__",
              [](Undefined const& val) -> std::string { return "UNDEFINED"; })
         .def(py::self < Undefined())
+        // TODO doesn't yet exist .def(py::self <= Undefined())
         .def(
             "__eq__",
             [](Undefined const& lhop, Undefined const& rhop) -> bool {
               return true;
             },
             py::is_operator())
-        .def("__hash__", [](Undefined const& op) -> int {
+        .def("__hash__", [](Undefined const& op) {
           return std::hash<uint64_t>{}(static_cast<uint64_t>(op));
         });
 
@@ -53,15 +59,26 @@ namespace libsemigroups {
     // PositiveInfinity
     ////////////////////////////////////////////////////////////////////////
 
-    py::class_<PositiveInfinity>(m, "PositiveInfinity")
+    py::class_<PositiveInfinity>(m,
+                                 "PositiveInfinity",
+                                 R"pbdoc(
+The type of :any:`POSITIVE_INFINITY`.
+
+This class is the type of the constant value :any:`POSITIVE_INFINITY`, and appears as
+such in type annotations in ``libsemigroups_pybind11``.
+)pbdoc")
         .def("__repr__",
              [](PositiveInfinity const& val) -> std::string {
                return u8"+\u221E";
              })
         .def(pybind11::self < PositiveInfinity())
+        // .def(pybind11::self <= PositiveInfinity())
         .def(pybind11::self < NegativeInfinity())
+        // .def(pybind11::self <= NegativeInfinity()) TODO not implemented
         .def(pybind11::self < int())
+        // .def(pybind11::self <= int()) TODO not implemented
         .def(int() < pybind11::self)
+        // .def(int() <= pybind11::self) TODO not implemented
         .def(
             "__eq__",
             [](PositiveInfinity const& lhop,
@@ -82,7 +99,14 @@ namespace libsemigroups {
     // NegativeInfinity
     ////////////////////////////////////////////////////////////////////////
 
-    py::class_<NegativeInfinity>(m, "NegativeInfinity")
+    py::class_<NegativeInfinity>(m,
+                                 "NegativeInfinity",
+                                 R"pbdoc(
+The type of :any:`NEGATIVE_INFINITY`.
+
+This class is the type of the constant value :any:`NEGATIVE_INFINITY`, and appears as
+such in type annotations in ``libsemigroups_pybind11``.
+)pbdoc")
         .def("__repr__",
              [](NegativeInfinity const& val) -> std::string {
                return u8"-\u221E";
@@ -106,7 +130,14 @@ namespace libsemigroups {
     // LimitMax
     ////////////////////////////////////////////////////////////////////////
 
-    py::class_<LimitMax>(m, "LimitMax")
+    py::class_<LimitMax>(m,
+                         "LimitMax",
+                         R"pbdoc(
+The type of :any:`LIMIT_MAX`.
+
+This class is the type of the constant value :any:`LIMIT_MAX`, and appears as
+such in type annotations in ``libsemigroups_pybind11``.
+)pbdoc")
         .def("__repr__",
              [](LimitMax const& val) -> std::string { return "LIMIT_MAX"; })
         .def(pybind11::self < LimitMax())

src/libsemigroups_pybind11/__init__.py

@@ -60,18 +60,22 @@
         Joiner,
         LIMIT_MAX,
         LibsemigroupsError,
+        LimitMax,
         Meeter,
         NEGATIVE_INFINITY,
+        NegativeInfinity,
         Order,
         PBR,
         POSITIVE_INFINITY,
         Paths,
+        PositiveInfinity,
         ReportGuard,
         StringRange,
         ToString,
         ToWord,
         UNDEFINED,
         Ukkonen,
+        Undefined,
         WordGraph,
         WordRange,
         congruence_kind,