Merge pull request #57 from mwcraig/add-gui-effects-to-docstrings

Describe GUI behavior

Author: mwcraig

src/astro_image_display_api/interface_definition.py

@@ -42,7 +42,8 @@ def load_image(self, data: Any, image_label: str | None = None) -> None:
 
         Notes
         -----
-        Loading an image should also set the viewport for that image.
+
+        Loading an image should also set an appropriate viewport for that image.
         """
         raise NotImplementedError
 
@@ -76,6 +77,11 @@ def set_cuts(
         ValueError
             If the ``image_label`` is not provided when there are multiple images loaded,
             or if the ``image_label`` does not correspond to a loaded image.
+
+        Notes
+        -----
+        Setting cuts should update the display of the image to reflect the new
+        cuts.
         """
         raise NotImplementedError
 
@@ -101,6 +107,10 @@ def get_cuts(self, image_label: str | None = None) -> BaseInterval:
         ValueError
             If the ``image_label`` is not provided when there are multiple images loaded,
             or if the ``image_label`` does not correspond to a loaded image.
+
+        Notes
+        -----
+        This has no effect on the displayed image.
         """
         raise NotImplementedError
 
@@ -127,6 +137,11 @@ def set_stretch(self, stretch: BaseStretch, image_label: str | None = None) -> N
         ValueError
             If the ``image_label`` is not provided when there are multiple images loaded
             or if the ``image_label`` does not correspond to a loaded image.
+
+        Notes
+        -----
+        Setting the stretch should update the display of the image to reflect the new
+        stretch.
         """
         raise NotImplementedError
 
@@ -146,6 +161,10 @@ def get_stretch(self, image_label: str | None = None) -> BaseStretch:
         -------
         stretch : `~astropy.visualization.BaseStretch`
             The Astropy stretch object representing the current stretch.
+
+        Notes
+        -----
+        This has no effect on the displayed image.
         """
         raise NotImplementedError
 
@@ -171,6 +190,12 @@ def set_colormap(self, map_name: str, image_label: str | None = None) -> None:
         ValueError
             If the ``map_name`` is not a valid colormap name or if the ``image_label``
             is not provided when there are multiple images loaded.
+
+        Notes
+        -----
+        This should update the display of the image to reflect the new colormap.
+
+        .. _Matplotlib: https://matplotlib.org/stable/gallery/color/colormap_reference.html
         """
         raise NotImplementedError
 
@@ -196,6 +221,10 @@ def get_colormap(self, image_label: str | None = None) -> str:
         ValueError
             If the ``image_label`` is not provided when there are multiple images loaded
             or if the ``image_label`` does not correspond to a loaded image.
+
+        Notes
+        -----
+        This has no effect on the displayed image.
         """
         raise NotImplementedError
 
@@ -219,6 +248,10 @@ def save(self, filename: str | os.PathLike, overwrite: bool = False) -> None:
         ------
         FileExistsError
             If the file already exists and ``overwrite`` is `False`.
+
+        Notes
+        -----
+        This has no effect on the displayed image.
         """
         raise NotImplementedError
 
@@ -267,6 +300,11 @@ def load_catalog(
             If the ``table`` does not contain the required columns, or if
             the ``catalog_label`` is not provided when there are multiple
             catalogs loaded.
+
+        Notes
+        -----
+        This should display the markers on the image in addition to storing
+        the marker positions in the viewer.
         """
         raise NotImplementedError
 
@@ -296,17 +334,20 @@ def set_catalog_style(
         **kwargs
             Additional keyword arguments to pass to the marker style.
 
-        Note
-        ----
-        The following shapes are supported: "circle", "square", "crosshair", "plus",
-        "diamond".
-
         Raises
         ------
         ValueError
             If there are multiple catalog styles set and the user has not
             specified a ``catalog_label`` for which to set the style, or if
             an style is set for a catalog that does not exist.
+
+        Notes
+        -----
+        The following shapes are supported: "circle", "square", "crosshair", "plus",
+        "diamond".
+
+        Changing the style of the markers should update the display of the
+        markers in the image.
         """
         raise NotImplementedError
 
@@ -336,6 +377,10 @@ def get_catalog_style(self, catalog_label: str | None = None) -> dict:
             If there are multiple catalog styles set and the user has not
             specified a ``catalog_label`` for which to get the style.
 
+        Notes
+        -----
+        This has no effect on the displayed image.
+
         """
         raise NotImplementedError
 
@@ -400,6 +445,10 @@ def get_catalog(
         ValueError
             If the ``catalog_label`` is not provided when there are multiple catalogs
             loaded.
+
+        Notes
+        -----
+        This has no effect on the displayed image.
         """
         raise NotImplementedError
 
@@ -412,6 +461,10 @@ def get_catalog_names(self) -> list[str]:
         -------
         list of str
             The names of the loaded catalogs.
+
+        Notes
+        -----
+        This has no effect on the displayed image.
         """
         raise NotImplementedError
 
@@ -453,6 +506,11 @@ def set_viewport(
 
         `astropy.units.UnitTypeError`
             If the ``fov`` is a `~astropy.units.Quantity` but does not have an angular unit.
+
+        Notes
+        -----
+        Setting the viewport should update the display of the image to reflect the new
+        viewport.
         """
         raise NotImplementedError
 
@@ -491,5 +549,9 @@ def get_viewport(
             If the ``sky_or_pixel`` parameter is not one of 'sky', 'pixel', or `None`,
             or if the ``image_label`` is not provided when there are multiple images
             loaded, or if the ``image_label`` does not correspond to a loaded image.
+
+        Notes
+        -----
+        This has no effect on the displayed image.
         """
         raise NotImplementedError