From e410d03f06a50e2a34407c5175836ef34dc5f7dd Mon Sep 17 00:00:00 2001
From: Genevieve Buckley <30920819+GenevieveBuckley@users.noreply.github.com>
Date: Fri, 18 Aug 2023 11:16:39 +1000
Subject: [PATCH] Docstrings describing inputs to writer functions (#154)

* Docstrings describing inputs to writer functions

* Update writer docstrings (include meta kwarg)

* Add @czaki's explanation of the meta dictionary

* Update _writer.py docstring (kwargs -> meta)

* Update _writer.py docstrings

* Update {{cookiecutter.plugin_name}}/src/{{cookiecutter.module_name}}/_writer.py

Co-authored-by: Juan Nunez-Iglesias <jni@fastmail.com>

* Update {{cookiecutter.plugin_name}}/src/{{cookiecutter.module_name}}/_writer.py

Co-authored-by: Juan Nunez-Iglesias <jni@fastmail.com>

* fix typo, missing `

---------

Co-authored-by: Juan Nunez-Iglesias <jni@fastmail.com>
Co-authored-by: Grzegorz Bokota <bokota+github@gmail.com>
Co-authored-by: Peter Sobolewski <76622105+psobolewskiPhD@users.noreply.github.com>
---
 .../{{cookiecutter.module_name}}/_writer.py   | 35 +++++++++++++++++--
 1 file changed, 33 insertions(+), 2 deletions(-)

diff --git a/{{cookiecutter.plugin_name}}/src/{{cookiecutter.module_name}}/_writer.py b/{{cookiecutter.plugin_name}}/src/{{cookiecutter.module_name}}/_writer.py
index 2812baa..e67fcc9 100644
--- a/{{cookiecutter.plugin_name}}/src/{{cookiecutter.module_name}}/_writer.py
+++ b/{{cookiecutter.plugin_name}}/src/{{cookiecutter.module_name}}/_writer.py
@@ -16,7 +16,22 @@
 
 
 def write_single_image(path: str, data: Any, meta: dict) -> List[str]:
-    """Writes a single image layer"""
+    """Writes a single image layer.
+    
+    Parameters
+    ----------
+    path : str
+        A string path indicating where to save the image file.
+    data : The layer data
+        The `.data` attribute from the napari layer.
+    meta : dict
+        A dictionary containing all other attributes from the napari layer
+        (excluding the `.data` layer attribute).
+
+    Returns
+    -------
+    [path] : A list containing the string path to the saved file.
+    """
 
     # implement your writer logic here ...
 
@@ -25,7 +40,23 @@ def write_single_image(path: str, data: Any, meta: dict) -> List[str]:
 
 
 def write_multiple(path: str, data: List[FullLayerData]) -> List[str]:
-    """Writes multiple layers of different types."""
+    """Writes multiple layers of different types.
+    
+    Parameters
+    ----------
+    path : str
+        A string path indicating where to save the data file(s).
+    data : A list of layer tuples.
+        Tuples contain three elements: (data, meta, layer_type)
+        `data` is the layer data
+        `meta` is a dictionary containing all other metadata attributes
+        from the napari layer (excluding the `.data` layer attribute).
+        `layer_type` is a string, eg: "image", "labels", "surface", etc.
+
+    Returns
+    -------
+    [path] : A list containing (potentially multiple) string paths to the saved file(s).
+    """
 
     # implement your writer logic here ...