From b031f8f85c29dd47aebe82c82e9d944d197e00ca Mon Sep 17 00:00:00 2001
From: Ken Lauer <klauer@slac.stanford.edu>
Date: Thu, 12 May 2022 11:10:06 -0700
Subject: [PATCH] DOC: DisplayFormat and parse_value_for_display

---
 docs/source/widgets/index.rst     |  8 +++++++
 docs/source/widgets/utilities.rst | 10 ++++++++
 pydm/widgets/display_format.py    | 39 +++++++++++++++++++++++++++++--
 3 files changed, 55 insertions(+), 2 deletions(-)
 create mode 100644 docs/source/widgets/utilities.rst

diff --git a/docs/source/widgets/index.rst b/docs/source/widgets/index.rst
index 075c93148..1c1ccdd69 100644
--- a/docs/source/widgets/index.rst
+++ b/docs/source/widgets/index.rst
@@ -61,3 +61,11 @@ Drawing Widgets
    :maxdepth: 1
 
    drawing.rst
+
+Utilities
+---------
+
+.. toctree::
+   :maxdepth: 1
+
+   utilities.rst
diff --git a/docs/source/widgets/utilities.rst b/docs/source/widgets/utilities.rst
new file mode 100644
index 000000000..72d6d88ca
--- /dev/null
+++ b/docs/source/widgets/utilities.rst
@@ -0,0 +1,10 @@
+########################
+Display Format Utilities
+########################
+
+.. currentmodule:: pydm.widgets.display_format
+
+.. autoclass:: DisplayFormat
+   :members:
+
+.. autofunction:: parse_value_for_display
diff --git a/pydm/widgets/display_format.py b/pydm/widgets/display_format.py
index 4243600d2..fc7e27465 100644
--- a/pydm/widgets/display_format.py
+++ b/pydm/widgets/display_format.py
@@ -1,5 +1,6 @@
 import math
 import numpy as np
+from typing import Any
 
 import logging
 import warnings
@@ -8,15 +9,49 @@
 
 
 class DisplayFormat(object):
+    """Display format for showing data in a PyDM widget."""
+    #: The default display format.
     Default = 0
+    #: Show the data as a string.
     String = 1
+    #: Show numerical values as floating point (base 10, decimal) values.
     Decimal = 2
+    #: Show numerical values in scientific / exponential notation.
     Exponential = 3
+    #: Show numerical values in base 16 (hexadecimal) notation.
     Hex = 4
+    #: Show numerical values in base 2 (binary) notation.
     Binary = 5
 
 
-def parse_value_for_display(value, precision, display_format_type=DisplayFormat.Default, string_encoding="utf_8", widget=None):
+def parse_value_for_display(
+    value: Any,
+    precision: int,
+    display_format_type: int = DisplayFormat.Default,
+    string_encoding: str = "utf_8",
+    widget=None,
+):
+    """
+    Format a value to show it in a widget, based on the display format type.
+
+    Parameters
+    ----------
+    value : Any
+        The value to convert to a string.
+    precision : int
+        Precision of floating point values to use.
+    display_format_type : int, optional
+        Display format type to use.
+    string_encoding : str, optional
+        Encoding to use for strings.
+    widget : QtWidgets.QWidget, optional
+        Widget to get a name from for conversion errors.
+
+    Returns
+    -------
+    str
+        Formatted version of ``value``.
+    """
     if value is None:
         return ""
     try:
@@ -37,7 +72,7 @@ def parse_value_for_display(value, precision, display_format_type=DisplayFormat.
                 if zeros.size > 0:
                     value = value[:zeros[0]]
                 r = value.tobytes().decode(string_encoding)
-            except:
+            except Exception:
                 logger.error("Could not decode {0} using {1} at widget named '{2}'.".format(
                     value, string_encoding, widget_name))
                 return value