Ambrogio: Code improvements

run_first.py

@@ -23,6 +23,13 @@
 
 
 def read_json(filename):
+    """Reads a JSON file and returns its contents as a dictionary.
+
+    Args:
+        filename (str): The path to the JSON file to be read.
+
+    Returns:
+        dict: The contents of the JSON file."""
     with open(filename) as f:
         data = json.load(f)
     return data

streamlit_app.py

@@ -38,6 +38,23 @@
 
 
 def create_star_graph(nodes_and_weights, title):
+    """Generates and displays a star graph visualization using Plotly.
+
+    This function creates a star-shaped graph with a central node labeled
+    "resume" connected to various nodes specified in the `nodes_and_weights`
+    list. Each connection (edge) is assigned a weight that influences the
+    layout and appearance of the graph. Nodes are color-coded based on the
+    number of connections they have.
+
+    Args:
+        nodes_and_weights (list of tuples): A list where each tuple contains
+            a node label (str) and a corresponding weight (float or int). The
+            weight affects the graph layout.
+        title (str): The title of the graph to be displayed.
+
+    Returns:
+        None: The function displays the graph using Streamlit's Plotly chart
+        feature but does not return any value."""
     # Create an empty graph
     G = nx.Graph()
 
@@ -131,6 +148,23 @@ def create_star_graph(nodes_and_weights, title):
 def create_annotated_text(
     input_string: str, word_list: List[str], annotation: str, color_code: str
 ):
+    """Annotates specific words within a given text with additional information.
+
+    This function takes an input string and searches for occurrences of words
+    from a specified list. When a match is found, it annotates the word with
+    the provided annotation and color code. The result is a list where each
+    word is either a plain string or a tuple containing the word, its annotation,
+    and its color code.
+
+    Args:
+        input_string (str): The text to search and annotate.
+        word_list (List[str]): A list of words to be annotated.
+        annotation (str): The annotation to associate with each word in the word list.
+        color_code (str): The color code to associate with each word in the word list.
+
+    Returns:
+        List[Union[str, Tuple[str, str, str]]]: A list where each element is either a
+        plain string or a tuple containing a word, its annotation, and its color code."""
     # Tokenize the input string
     tokens = nltk.word_tokenize(input_string)
 
@@ -153,12 +187,26 @@ def create_annotated_text(
 
 
 def read_json(filename):
+    """Reads a JSON file and returns the parsed data.
+
+    Args:
+        filename (str): The path to the JSON file to be read.
+
+    Returns:
+        dict: The data parsed from the JSON file."""
     with open(filename) as f:
         data = json.load(f)
     return data
 
 
 def tokenize_string(input_string):
+    """Tokenizes the input string into individual words.
+
+    Args:
+        input_string (str): The string to be tokenized.
+
+    Returns:
+        list of str: A list of tokens (words) extracted from the input string."""
     tokens = nltk.word_tokenize(input_string)
     return tokens
 

streamlit_second.py

@@ -32,6 +32,19 @@
 
 
 def create_star_graph(nodes_and_weights, title):
+    """Generates and displays a star graph visualization.
+
+    This function creates a star graph with a central node labeled 'resume'
+    and additional nodes connected to it. Each connection is weighted according 
+    to the provided list of node-weight pairs. The graph is visualized using Plotly.
+
+    Args:
+        nodes_and_weights (list of tuple): A list where each tuple contains a node 
+            name (str) and its corresponding weight (float).
+        title (str): The title of the graph.
+
+    Returns:
+        None: The function displays the graph using Streamlit and Plotly."""
     # Create an empty graph
     G = nx.Graph()
 
@@ -125,6 +138,24 @@ def create_star_graph(nodes_and_weights, title):
 def create_annotated_text(
     input_string: str, word_list: List[str], annotation: str, color_code: str
 ):
+    """Annotates specified words in the input string with additional information.
+
+    This function tokenizes the input string and checks each token against a list
+    of specified words. If a token is found in the list, it is annotated with
+    additional information including an annotation label and a color code. The
+    result is a list where each word is either a string (if unannotated) or a 
+    tuple consisting of the word, its annotation, and the color code.
+
+    Args:
+        input_string (str): The string to be processed and annotated.
+        word_list (List[str]): A list of words to be annotated.
+        annotation (str): The annotation label to attach to words found in the word list.
+        color_code (str): The color code to attach to the annotated words.
+
+    Returns:
+        List[Union[str, Tuple[str, str, str]]]: A list of tokens from the input string,
+        where tokens that match words in the word list are tuples containing the
+        token, annotation, and color code; other tokens remain as strings."""
     # Tokenize the input string
     tokens = nltk.word_tokenize(input_string)
 
@@ -147,12 +178,26 @@ def create_annotated_text(
 
 
 def read_json(filename):
+    """Reads a JSON file and returns its content as a Python object.
+
+    Args:
+        filename (str): The path to the JSON file to be read.
+
+    Returns:
+        dict or list: The JSON content parsed into a Python dictionary or list."""
     with open(filename) as f:
         data = json.load(f)
     return data
 
 
 def tokenize_string(input_string):
+    """Tokenizes a given string into individual words.
+
+    Args:
+        input_string (str): The string to be tokenized.
+
+    Returns:
+        list: A list of word tokens extracted from the input string."""
     tokens = nltk.word_tokenize(input_string)
     return tokens
 
@@ -461,6 +506,18 @@ def tokenize_string(input_string):
 
 
 def plot_df(df, title):
+    """Generates and displays a bar chart of scores using Plotly.
+
+    This function takes a DataFrame containing 'text' and 'score' columns,
+    creates a bar chart with 'text' as the x-axis and 'score' multiplied by 100
+    as the y-axis, and displays it with Streamlit.
+
+    Args:
+        df (pandas.DataFrame): A DataFrame containing at least 'text' and 'score' columns.
+        title (str): The title of the bar chart.
+
+    Returns:
+        None"""
     fig = px.bar(df, x="text", y=df["score"] * 100, title=title)
     st.plotly_chart(fig)