Clarify user expectations for getStatNames

Doc/source/designspaceLib/xml.rst

@@ -814,12 +814,12 @@ The ``<instances>`` element contains one or more ``<instance>`` elements.
 
 .. rubric:: Attributes
 
--  ``familyname``: required, string. The family name of the instance
-   font. Corresponds with ``font.info.familyName``
--  ``stylename``: required, string. The style name of the instance font.
-   Corresponds with ``font.info.styleName``
--  ``name``: required, string. A unique name that can be used to
-   identify this font if it needs to be referenced elsewhere.
+-  ``familyname``: string. Optional if the default source has it set. The family
+   name of the instance font. Corresponds with ``font.info.familyName``
+-  ``stylename``: string. Optional if all axes are fully labled. The style name
+   of the instance font. Corresponds with ``font.info.styleName``
+-  ``name``: string. Optional if all axes are fully labled. A unique name that
+   can be used to identify this font if it needs to be referenced elsewhere.
 -  ``filename``: string. Required for MutatorMath. A path to the
    instance file, relative to the root path of this document. The path
    can be at the same level as the document or lower.

Lib/fontTools/designspaceLib/statNames.py

@@ -60,6 +60,10 @@ def getStatNames(
     localized names will be empty (family and style names), or the name will be
     None (PostScript name).
 
+    Note: this method does not consider info attached to the instance, like
+    family name. The user needs to override all names on an instance that STAT
+    information would compute differently than desired.
+
     .. versionadded:: 5.0
     """
     familyNames: Dict[str, str] = {}