Repository: PrefectHQ/prefect

Issue:
Add docs for `Result` / `NoResult`
We need to both add the classes to the API docs + add a concept doc for these objects.


Discussion:

Resolving patch:
diff --git a/docs/generate_docs.py b/docs/generate_docs.py
--- a/docs/generate_docs.py
+++ b/docs/generate_docs.py
@@ -246,7 +246,8 @@ def format_subheader(obj, level=1, in_table=False):
         header = "|"
     is_class = "<strong><em>class </em></strong>" if inspect.isclass(obj) else ""
     class_name = f"<strong>{create_absolute_path(obj)}</strong>"
-    div_tag = f"<div class='sig'>"
+    div_class = "class-sig" if is_class else "method-sig"
+    div_tag = f"<div class='{div_class}'>"
 
     call_sig = f" {header} {div_tag}{is_class}{class_name}({class_sig}){get_source(obj)}</div>\n\n"
     return call_sig
diff --git a/src/prefect/engine/result.py b/src/prefect/engine/result.py
--- a/src/prefect/engine/result.py
+++ b/src/prefect/engine/result.py
@@ -1,4 +1,22 @@
 # Licensed under LICENSE.md; also available at https://www.prefect.io/licenses/alpha-eula
+"""
+Results represent Prefect Task inputs and outputs.  In particular, anytime a Task runs, its output
+is encapsulated in a `Result` object.  This object retains information about what the data is, and how to "handle" it
+if it needs to be saved / retrieved at a later time (for example, if this Task requests for its outputs to be cached).
+
+An instantiated Result object has the following attributes:
+
+- a `value`: the value of a Result represents a single piece of data, which can be
+    in raw form or compressed into a "handled" representation such as a URI or filename pointing to
+    where the raw form lives
+- a `handled` boolean specifying whether this `value` has been handled or not
+- a `result_handler` which holds onto the `ResultHandler` used to read /
+    write the value to / from its handled representation
+
+To distinguish between a Task which runs but does not return output from a Task which has yet to run, Prefect
+also provides a `NoResult` object representing the _absence_ of computation / data.  This is in contrast to a `Result`
+whose value is `None`.
+"""
 
 from typing import Any, Union
 
@@ -82,6 +100,11 @@ def read(self) -> "Result":
 
 
 class NoResultType(Result):
+    """
+    A `Result` subclass representing the _absence_ of computation / output.  A `NoResult` object
+    simply returns itself for its `value`, and as the output of both `read` and `write`.
+    """
+
     def __init__(self) -> None:
         pass
 
@@ -99,9 +122,15 @@ def value(self) -> "NoResultType":
         return self
 
     def read(self) -> "NoResultType":
+        """
+        Performs no computation and returns self.
+        """
         return self
 
     def write(self) -> "NoResultType":
+        """
+        Performs no computation and returns self.
+        """
         return self
 
 
diff --git a/src/prefect/engine/result_handlers/__init__.py b/src/prefect/engine/result_handlers/__init__.py
--- a/src/prefect/engine/result_handlers/__init__.py
+++ b/src/prefect/engine/result_handlers/__init__.py
@@ -1,4 +1,8 @@
 # Licensed under LICENSE.md; also available at https://www.prefect.io/licenses/alpha-eula
+"""
+Result handler is simply a specific implementation of a `read` / `write` interface for handling data.
+The only requirement for a Result handler implementation is that the `write` method returns a JSON-compatible object.
+"""
 
 from prefect.engine.result_handlers.result_handler import ResultHandler
 from prefect.engine.result_handlers.json_result_handler import JSONResultHandler


Test patch:
diff --git a/docs/test_generate_docs.py b/docs/test_generate_docs.py
--- a/docs/test_generate_docs.py
+++ b/docs/test_generate_docs.py
@@ -156,7 +156,7 @@ def test_create_absolute_path_on_nonprefect_object(obj, exp):
 def test_format_subheader_on_class():
     doc = format_subheader(A)
     assert doc == (
-        "  <div class='sig'>"
+        "  <div class='class-sig'>"
         "<strong><em>class </em></strong><strong>A</strong>(attr, keep=True)<span>[source]</span></div>\n\n"
     )
 
diff --git a/tests/engine/result_handlers/__init__.py b/tests/engine/result_handlers/__init__.py
--- a/tests/engine/result_handlers/__init__.py
+++ b/tests/engine/result_handlers/__init__.py
@@ -0,0 +1,2 @@
+
+