diff --git a/src/FacetSource/FacetSourcePluginInterface.php b/src/FacetSource/FacetSourcePluginInterface.php
index 9c3cc86..255d049 100644
--- a/src/FacetSource/FacetSourcePluginInterface.php
+++ b/src/FacetSource/FacetSourcePluginInterface.php
@@ -99,16 +99,27 @@ public function setSearchKeys($keys);
   public function getSearchKeys();
 
   /**
-   * Returns the defined fields indexed on the facet source.
+   * Returns an array of data definitions for all fields for this facet source.
+   *
+   * For search api this means that we load the index and call it's getFields
+   * method to find all fields and return the typed data objects for all fields.
+   * For core search, the approach is different but we'll also return the typed
+   * data objects for all fields.
    *
    * @return \Drupal\Core\TypedData\DataDefinitionInterface[]
+   *   An array of typed data definitions.
    */
   public function getDataDefinitions();
 
   /**
-   * Returns one defined field from the facet source.
+   * Returns a single field's data definition from the facet source.
+   *
+   * Uses ::getDataDefinitions internally to select one of the fields.
+   *
+   * @see ::getDataDefinitions
    *
    * @return \Drupal\Core\TypedData\DataDefinitionInterface
+   *   A typed data definition.
    */
   public function getDataDefinition($field_name);