From cc57804e465c3a006fffd9cf6e4b9b55cd41cb9f Mon Sep 17 00:00:00 2001
From: Stefaan Lippens <stefaan.lippens@vito.be>
Date: Wed, 12 Feb 2025 15:57:32 +0100
Subject: [PATCH] #720/#402/#725 document SaveResult design background a bit
 more

---
 docs/api.rst          |  1 +
 openeo/rest/result.py | 31 ++++++++++++++++++++++++++++---
 2 files changed, 29 insertions(+), 3 deletions(-)

diff --git a/docs/api.rst b/docs/api.rst
index 0f5dd57be..745a02532 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -54,6 +54,7 @@ Results
 
 .. automodule:: openeo.rest.result
    :members:
+   :inherited-members:
 
 .. automodule:: openeo.rest.stac_resource
    :members:
diff --git a/openeo/rest/result.py b/openeo/rest/result.py
index 08aa05b4a..49451d74a 100644
--- a/openeo/rest/result.py
+++ b/openeo/rest/result.py
@@ -3,10 +3,35 @@
 
 class SaveResult(StacResource):
     """
-    Alias for :py:class:`~openeo.rest.stac_resource.StacResource`,
-    returned by methods corresponding to the openEO process ``save_result``, like
+    Handle for a process graph that represents the return value
+    of the openEO process ``save_result``,
+    as returned by methods like
     :py:meth:`DataCube.save_result() <openeo.rest.datacube.DataCube.save_result>`
-    and :py:meth:`VectorCube.save_result() <openeo.rest.vectorcube.VectorCube.save_result>`
+    and :py:meth:`VectorCube.save_result() <openeo.rest.vectorcube.VectorCube.save_result>`.
+
+    .. note ::
+        This class is practically a just direct alias for
+        :py:class:`~openeo.rest.stac_resource.StacResource`,
+        but with a more self-explanatory name.
+
+        Moreover, this additional abstraction layer also acts somewhat as an adapter between
+        the incompatible return values from the ``save_result`` process
+        in different versions of the official openeo-processes definitions:
+
+        - in openeo-processes 1.x: ``save_result`` just returned a boolean,
+          but that was not really useful to further build upon
+          and was never properly exposed in the openEO Python client.
+        - in openeo-processes 2.x: ``save_result`` returns a new concept:
+          a "STAC resource" (object with subtype "stac")
+          which is a more useful and flexible representation of an openEO result,
+          allowing additional operations.
+
+        The openEO Python client returns the same :py:class:`SaveResult` object
+        in both cases however.
+        It does that not only for simplicity,
+        but also because it seems more useful (even in legacy openeo-processes 1.x use cases)
+        to follow the new STAC resource based usage patterns
+        than to strictly return some boolean wrapper nobody has use for.
 
     .. versionadded:: 0.39.0
     """