DOC: improved docstrings for some functions

src/caosdb/utils/plantuml.py

@@ -42,6 +42,18 @@ REFERENCE = "REFERENCE"
 
 
 def get_description(description_str):
+    """Extract and format a description string from a record type or property.
+
+    Parameters
+    ----------
+    description_str : str
+                      The description string that is going to be formatted.
+
+    Returns
+    -------
+    str
+       The reformatted description ending in a line break.
+    """
     words = description_str.split()
     lines = []
     lines.append("")
@@ -211,18 +223,6 @@ package \"The property P references an instance of D\" <<Rectangle>> {
 
     return result
 
-
-def to_graphics(recordtypes, filename):
-    """ calls recordtypes_to_plantuml_string(), saves result to file and
-    creates an svg image
-
-    plantuml needs to be installed
-    @params:
-    recordtypes: itrable with the record types to be displayed
-    filname: filename of the image (e.g. data_structure; data_structure.pu and
-    data_structure.svg will be created.
-    """
-    pu = recordtypes_to_plantuml_string(recordtypes)
 def retrieve_substructure(start_record_types, depth, result_id_set=None, result_container=None, cleanup=True):
     """Recursively retrieves CaosDB record types and properties, starting
     from given initial types up to a specific depth.
@@ -280,6 +280,22 @@ def retrieve_substructure(start_record_types, depth, result_id_set=None, result_
     return None
         
     
+def to_graphics(recordtypes, filename):
+    """Calls recordtypes_to_plantuml_string(), saves result to file and
+    creates an svg image
+
+    plantuml needs to be installed.
+    
+    Parameters
+    ----------
+    recordtypes : Iterable[db.Entity]
+                  Iterable with the entities to be displayed.
+    filename : str
+               filename of the image without the extension(e.g. data_structure;
+               data_structure.pu and data_structure.svg will be created.)
+    """
+    pu = recordtypes_to_plantuml_string(recordtypes)
+
 
     pu_filename = filename+".pu"
     with open(pu_filename, "w") as pu_file: