Merge #2162

2162: Update API docs on saturation, rewards, and relative stake r=Anviking a=Anviking

# Issue Number

#2155 

# Overview

<!-- Detail in a few bullet points the work accomplished in this PR -->

- [x] Tweaked API docs


# Comments

- Not sure if we should rush this to be in the release or not

<!-- Additional comments or screenshots to attach if any -->

<!-- 
Don't forget to:

 ✓ Self-review your changes to make sure nothing unexpected slipped through
 ✓ Assign yourself to the PR
 ✓ Assign one or several reviewer(s)
 ✓ Once created, link this PR to its corresponding ticket
 ✓ Assign the PR to a corresponding milestone
 ✓ Acknowledge any changes required to the Wiki
-->


Co-authored-by: Johannes Lund <[email protected]>

specifications/api/swagger.yaml

@@ -739,12 +739,26 @@ x-stakePoolMargin: &stakePoolMargin
 
       May be omitted if the wallet hasn't found the pool's registration cerificate yet.
 
+x-jormungandrStakePoolSaturation: &jormungandrStakePoolSaturation
+  type: number
+  minimum: 0
+  description: |
+    Saturation-level of the pool based on the desired number of pools aimed by the network.
+    A value above `1` indicates that the pool is saturated.
+  example: 0.74
+
 x-stakePoolSaturation: &stakePoolSaturation
   type: number
   minimum: 0
   description: |
     Saturation-level of the pool based on the desired number of pools aimed by the network.
     A value above `1` indicates that the pool is saturated.
+
+    The `non_myopic_member_rewards` take oversaturation into account, as specified by the [specs](https://hydra.iohk.io/job/Cardano/cardano-ledger-specs/delegationDesignSpec/latest/download-by-type/doc-pdf/delegation_design_spec).
+
+    The saturation is based on the live `relative_stake`. The saturation at the end of epoch e,
+    will affect the rewards paid out at the end of epoch e+3.
+
   example: 0.74
 
 x-stakePoolDesirability: &stakePoolDesirability
@@ -776,11 +790,15 @@ x-stakePoolMetrics: &stakePoolMetrics
     non_myopic_member_rewards: *nonMyopicMemberRewards
     relative_stake:
       <<: *percentage
-      description: The pools stake compared to the stake of all pools.
+      description: |
+        The live pool stake relative to the *total* stake.
+
+        For more details, see the section "Relative Stake: Active vs Total" in
+        [Design Specification for Delegation and Incentives in Cardano](https://hydra.iohk.io/job/Cardano/cardano-ledger-specs/delegationDesignSpec/latest/download-by-type/doc-pdf/delegation_design_spec).
     saturation: *stakePoolSaturation
     produced_blocks:
       <<: *numberOfBlocks
-      description: Number of blocks produced by a given stake pool
+      description: Number of blocks produced by a given stake pool in its lifetime.
 
 x-jormungandrStakePoolMetrics: &jormungandrStakePoolMetrics
   type: object
@@ -984,7 +1002,7 @@ components:
         cost: *jormungandrStakePoolCost
         margin: *jormungandrStakePoolMargin
         metadata: *jormungandrStakePoolMetadata
-        saturation: *stakePoolSaturation
+        saturation: *jormungandrStakePoolSaturation
         desirability: *stakePoolDesirability
 
     ApiFee: &ApiFee