From 97d534c5d10c064dc033d58c1ff434696d1fc1c5491eb47fe120bdd004d3a37c Mon Sep 17 00:00:00 2001
From: PioApocalypse <pioapocalypse@proton.me>
Date: Thu, 12 Feb 2026 12:15:25 +0100
Subject: [PATCH] documents main.py functions

---
 src/main.py | 25 ++++++++++++++++++++++---
 1 file changed, 22 insertions(+), 3 deletions(-)

diff --git a/src/main.py b/src/main.py
index 5f310a1..a6d82f0 100644
--- a/src/main.py
+++ b/src/main.py
@@ -5,6 +5,11 @@ from classes import *
 
 
 def call_entrypoint_from_elabid(elabid):
+    '''
+    Calls an entrypoint sample from eLabFTW using its elabid, then returns an object of the Entrypoint class.
+
+    If the entry is not a sample (category_title not matching exactly "Sample") returns ValueError.
+    '''
     try: 
         sample_data = APIHandler(apikey).get_entry_from_elabid(elabid, entryType="items")
         if not sample_data.get("category_title") == "Sample":
@@ -15,6 +20,12 @@ def call_entrypoint_from_elabid(elabid):
     return sample_object # Entrypoint-class object
 
 def call_material_from_elabid(elabid):
+    '''
+    Calls a material from eLabFTW using its elabid, then returns an object of the Material class.
+
+    If the entry is neither a PLD Target or a Substrate batch returns ValueError. Such entries always have a category_title key with its value either being "PLD Target" or "Substrate batch".
+    Because of an old typo, the value "Subtrate batch" (second 's' is missing) is also accepted.
+    '''
     try: 
         material_data = APIHandler(apikey).get_entry_from_elabid(elabid, entryType="items")
         # TO-DO: correct this typo on elabftw: Subtrate → Substrate.
@@ -26,6 +37,11 @@ def call_material_from_elabid(elabid):
     return material_object # Material-class object
 
 def call_layers_from_list(elabid_list):
+    '''
+    Calls a list of (PLD deposition) experiments from eLabFTW using their elabid - which means the input must be a list of integers instead of a single one - then returns a list of Layer-class objects.
+
+    If one of the entries is not related to a deposition layer (category_title not matching exactly "PLD Deposition") that entry is skipped, with no error raised.
+    '''
     list_of_layers = []
     for elabid in elabid_list:
         try:
@@ -37,17 +53,20 @@ def call_layers_from_list(elabid_list):
         except ConnectionError as e:
             nums = [ layer.layer_number for layer in list_of_layers ]
             nums.sort()
-            print(f"LISTA DEI LAYER PROCESSATI FINORA (in ordine sparso):\n" + str(nums))
+            print(f"LIST OF THE LAYERS PROCESSED (unordered):\n" + str(nums))
             raise ConnectionError(f"An error occurred while fetching the experiment with elabid = {elabid}:\n" +
                 str(e) + f"\nPlease solve the problem before retrying." + "\n\n" +
                 f"Last resource attempted to call: {ELABFTW_API_URL}/experiments/{elabid}"
             )
     return list_of_layers # list of Layer-class objects
 
-def from_entrypoint_to_material(sample_object):
+def call_batch_from_entrypoint(sample_object):
+    '''
+    Takes an Entrypoint-class object, looks at its .batch_elabid attribute and returns a Material-class object containing data on the substrate batch associated to the starting sample.
+    '''
     material_elabid = sample_object.batch_elabid
     material_object = call_material_from_elabid(material_elabid)
-    return sample_object, material_object
+    return material_object
 
 sample_object = call_entrypoint_from_elabid(elabid)
 from_entrypoint_to_material(sample_object)