Repository: Pyomo/pyomo

Issue:
Improve Sphinx docstrings for pyomo.util.config
#391 introduced additional validators for ConfigValue objects, but as was pointed out in the review, these classes need additional docstrings.


Discussion:

Resolving patch:
diff --git a/pyomo/common/config.py b/pyomo/common/config.py
--- a/pyomo/common/config.py
+++ b/pyomo/common/config.py
@@ -37,6 +37,10 @@
 DEVELOPER_OPTION = 2
 
 def PositiveInt(val):
+    """Domain validation function admitting strictly positive integers
+
+    This domain will admit positive integers, as well as any types that are convertible to positive integers.
+    """
     ans = int(val)
     # We want to give an error for floating point numbers...
     if ans != float(val) or ans <= 0:
@@ -45,6 +49,10 @@ def PositiveInt(val):
     return ans
 
 def NegativeInt(val):
+    """Domain validation function admitting strictly negative integers
+
+    This domain will admit negative integers, as well as any types that are convertible to negative integers.
+    """
     ans = int(val)
     if ans != float(val) or ans >= 0:
         raise ValueError(
@@ -52,6 +60,10 @@ def NegativeInt(val):
     return ans
 
 def NonPositiveInt(val):
+    """Domain validation function admitting non-positive integers (smaller than or equal to zero)
+
+    This domain will admit non-positive integers, as well as any types that are convertible to non-positive integers.
+    """
     ans = int(val)
     if ans != float(val) or ans > 0:
         raise ValueError(
@@ -59,6 +71,10 @@ def NonPositiveInt(val):
     return ans
 
 def NonNegativeInt(val):
+    """Domain validation function admitting non-negative integers (greater than or equal to zero)
+
+    This domain will admit non-negative integers, as well as any types that are convertible to non-negative integers.
+    """
     ans = int(val)
     if ans != float(val) or ans < 0:
         raise ValueError(
@@ -66,6 +82,10 @@ def NonNegativeInt(val):
     return ans
 
 def PositiveFloat(val):
+    """Domain validation function admitting strictly positive floating point numbers
+
+    This domain will admit positive floating point numbers, as well as any types that are convertible to positive floating point numbers.
+    """
     ans = float(val)
     if ans <= 0:
         raise ValueError(
@@ -73,6 +93,10 @@ def PositiveFloat(val):
     return ans
 
 def NegativeFloat(val):
+    """Domain validation function admitting strictly negative floating point numbers
+
+    This domain will admit negative floating point numbers, as well as any types that are convertible to negative floating point numbers.
+    """
     ans = float(val)
     if ans >= 0:
         raise ValueError(
@@ -80,6 +104,10 @@ def NegativeFloat(val):
     return ans
 
 def NonPositiveFloat(val):
+    """Domain validation function admitting strictly non-positive floating point numbers (smaller than or equal to zero)
+
+    This domain will admit non-positive floating point numbers, as well as any types that are convertible to non-positive floating point numbers.
+    """
     ans = float(val)
     if ans > 0:
         raise ValueError(
@@ -87,6 +115,10 @@ def NonPositiveFloat(val):
     return ans
 
 def NonNegativeFloat(val):
+    """Domain validation function admitting strictly non-negative floating point numbers (greater than or equal to zero)
+
+    This domain will admit non-negative floating point numbers, as well as any types that are convertible to non-negative floating point numbers.
+    """
     ans = float(val)
     if ans < 0:
         raise ValueError(
@@ -95,6 +127,7 @@ def NonNegativeFloat(val):
 
 
 class In(object):
+    """Domain validation function admitting a list of possible values that a variable can be assigned to."""
     def __init__(self, domain, cast=None):
         self._domain = domain
         self._cast = cast


Test patch: