pybricks.hubs: Update storage documentation.

This moves the per-hub storage size to the respective page.

This also clarifies that data is cleared when updating Powered Up hubs.

Also flip docstring signatures around to work around #117

doc/main/hubs/cityhub.rst

@@ -35,6 +35,10 @@ City Hub
 
     .. automethod:: pybricks.hubs::CityHub.system.storage
 
+        You can store up to 128 bytes of data on this hub. The data is cleared
+        when you update the Pybricks firmware or if you restore the original
+        firmware.
+
     .. automethod:: pybricks.hubs::CityHub.system.shutdown
 
     .. automethod:: pybricks.hubs::CityHub.system.reset_reason

doc/main/hubs/essentialhub.rst

@@ -67,6 +67,8 @@ Essential Hub
 
     .. automethod:: pybricks.hubs::EssentialHub.system.storage
 
+        You can store up to 512 bytes of data on this hub.
+
     .. automethod:: pybricks.hubs::EssentialHub.system.shutdown
 
     .. automethod:: pybricks.hubs::EssentialHub.system.reset_reason

doc/main/hubs/movehub.rst

@@ -47,6 +47,10 @@ Move Hub
 
     .. automethod:: pybricks.hubs::MoveHub.system.storage
 
+        You can store up to 128 bytes of data on this hub. The data is cleared
+        when you update the Pybricks firmware or if you restore the original
+        firmware.
+
     .. automethod:: pybricks.hubs::MoveHub.system.shutdown
 
     .. automethod:: pybricks.hubs::MoveHub.system.reset_reason

doc/main/hubs/primehub.rst

@@ -106,6 +106,8 @@ Prime Hub / Inventor Hub
 
     .. automethod:: pybricks.hubs::PrimeHub.system.storage
 
+        You can store up to 512 bytes of data on this hub.
+
     .. automethod:: pybricks.hubs::PrimeHub.system.shutdown
 
     .. automethod:: pybricks.hubs::PrimeHub.system.reset_reason

doc/main/hubs/technichub.rst

@@ -49,6 +49,10 @@ Technic Hub
 
     .. automethod:: pybricks.hubs::TechnicHub.system.storage
 
+        You can store up to 128 bytes of data on this hub. The data is cleared
+        when you update the Pybricks firmware or if you restore the original
+        firmware.
+
     .. automethod:: pybricks.hubs::TechnicHub.system.shutdown
 
     .. automethod:: pybricks.hubs::TechnicHub.system.reset_reason

src/pybricks/_common.py

@@ -78,20 +78,23 @@ def storage(self, offset: int, *, write: bytes) -> None:
 
     def storage(self, offset, read=None, write=None):
         """
-        storage(self, offset, read=) -> bytes
         storage(self, offset, write=)
+        storage(self, offset, read=) -> bytes
 
         Reads or writes binary data to persistent storage.
 
-        The available storage size is 128 bytes on Move, City and Technic hubs
-        and 512 bytes on SPIKE and MINDSTORMS hubs.
+        This lets you store data that can be used the next time you run the
+        program.
+
+        The data will be saved to flash memory when you turn the hub off
+        normally. It will not be saved if the batteries are removed *while* the
+        hub is still running.
 
-        .. note:: The data is written to flash memory on shutdown, so will only
-            be saved if the hub is properly shut down. It will not be saved if
-            the batteries are removed while the hub is still running.
+        Once saved, the data will remain available even after you remove the
+        batteries.
 
         Args:
-            offset (int): The offset from the start of the user storage memory in bytes.
+            offset (int): The offset from the start of the user storage memory, in bytes.
             read (int): The number of bytes to read. Omit this argument when writing.
             write (bytes): The bytes to write. Omit this argument when reading.
 
@@ -100,8 +103,7 @@ def storage(self, offset, read=None, write=None):
 
         Raises:
             ValueError:
-                The offset and/or the size of bytes to be read/written are
-                outside of the range of the allocated memory.
+                If you try to read or write data outside of the allowed range.
         """