WIP: Documentation improvement and format change to Google

src/libbot/utils/json/_functions.py

@@ -14,13 +14,13 @@ except ImportError:
 
 @asyncable
 def json_read(path: str | Path) -> Any:
-    """Read contents of a JSON file
+    """Read contents of a JSON file and return it.
 
-    ### Args:
-        * path (`str | Path`): Path-like object or path as a string
+    Args:
+        path (str | Path): Path-like object or path to the file as a string.
 
-    ### Returns:
-        * `Any`: File contents
+    Returns:
+        Any: File contents.
     """
     with open(str(path), mode="r", encoding="utf-8") as f:
         data = f.read()
@@ -30,13 +30,13 @@ def json_read(path: str | Path) -> Any:
 
 @json_read.asynchronous
 async def json_read(path: str | Path) -> Any:
-    """Read contents of a JSON file
+    """Read contents of a JSON file and return it.
 
-    ### Args:
-        * path (`str | Path`): Path-like object or path as a string
+    Args:
+        path (str | Path): Path-like object or path to the file as a string.
 
-    ### Returns:
-        * `Any`: File contents
+    Returns:
+        Any: File contents.
     """
     async with aiofiles.open(str(path), mode="r", encoding="utf-8") as f:
         data = await f.read()
@@ -46,11 +46,11 @@ async def json_read(path: str | Path) -> Any:
 
 @asyncable
 def json_write(data: Any, path: str | Path) -> None:
-    """Write contents to a JSON file
+    """Write contents to a JSON file.
 
-    ### Args:
-        * data (`Any`): Contents to write. Must be a JSON serializable
-        * path (`str | Path`): Path-like object or path as a string of a destination
+    Args:
+        data (Any): Contents to write. Must be a JSON-serializable object.
+        path (str | Path): Path-like object or path to the file as a string.
     """
     with open(str(path), mode="w", encoding="utf-8") as f:
         f.write(
@@ -62,11 +62,11 @@ def json_write(data: Any, path: str | Path) -> None:
 
 @json_write.asynchronous
 async def json_write(data: Any, path: str | Path) -> None:
-    """Write contents to a JSON file
+    """Write contents to a JSON file.
 
-    ### Args:
-        * data (`Any`): Contents to write. Must be a JSON serializable
-        * path (`str | Path`): Path-like object or path as a string of a destination
+    Args:
+        data (Any): Contents to write. Must be a JSON-serializable object.
+        path (str | Path): Path-like object or path to the file as a string.
     """
     async with aiofiles.open(str(path), mode="w", encoding="utf-8") as f:
         await f.write(