added a docstring

inventory_provider/routes/poller.py

@@ -48,6 +48,11 @@ These endpoints are intended for use by BRIAN.
 .. autofunction:: inventory_provider.routes.poller.get_service_types
 
 
+support method: _get_dashboards
+---------------------------------
+
+.. autofunction:: inventory_provider.routes.poller._get_dashboards
+
 """
 from enum import Enum, auto
 import json
@@ -95,6 +100,9 @@ class BRIAN_DASHBOARDS(Enum):
     CAE1 = auto()
 
 
+# only used in INTERFACE_LIST_SCHEMA and sphinx docs
+_DASHBOARD_IDS = [d.name for d in list(BRIAN_DASHBOARDS)]
+
 INTERFACE_LIST_SCHEMA = {
     '$schema': 'http://json-schema.org/draft-07/schema#',
 
@@ -134,7 +142,7 @@ INTERFACE_LIST_SCHEMA = {
                 },
                 'dashboards': {
                     'type': 'array',
-                    'items': {'enum': [d.name for d in list(BRIAN_DASHBOARDS)]}
+                    'items': {'enum': _DASHBOARD_IDS}
                 }
             },
             'required': [
@@ -328,6 +336,20 @@ def after_request(resp):
 
 
 def _get_dashboards(interface):
+    """
+    Yield enums from BRIAN_DASHBOARDS to indicate which dashboards
+    this interface should be included in.
+
+    cf. POL1-482
+
+    Possible dashboard id's are:
+
+    .. asjson::
+       inventory_provider.routes.poller._DASHBOARD_IDS
+
+    :param interface: a dict with keys like router, name, description
+    :return: generator that yields enums from BRIAN_DASHBOARDS
+    """
 
     router = interface.get('router', '').lower()
     ifc_name = interface.get('name', '')
@@ -607,6 +629,9 @@ def interfaces(hostname=None):
     .. asjson::
        inventory_provider.routes.poller.INTERFACE_LIST_SCHEMA
 
+    :meth:`inventory_provider.routes.poller._get_services`
+    is where dashboard mappings is handled.
+
     :param hostname: optional, if present should be a router hostname
     :return:
     """