From 790e736ef74f3e1b78e767760e005cea8c89066e Mon Sep 17 00:00:00 2001
From: David Straub <straub@protonmail.com>
Date: Sat, 1 Feb 2025 15:21:05 +0100
Subject: [PATCH] More doc strings

---
 yclade/find.py | 18 +++++++++++++++---
 yclade/snps.py | 10 +++++++++-
 2 files changed, 24 insertions(+), 4 deletions(-)

diff --git a/yclade/find.py b/yclade/find.py
index 751afbf..598bf9f 100644
--- a/yclade/find.py
+++ b/yclade/find.py
@@ -38,7 +38,7 @@ def get_node_match_info(
 def get_all_nodes_match_info(
     tree: YTreeData, snps: SnpResults
 ) -> dict[CladeName, CladeMatchInfo]:
-    """Find the nodes in the tree that have overlap with postive or negative SNPs."""
+    """Get the match info for all nodes in the tree."""
     node_info = {}
     for clade, clade_snps in tree.clade_snps.items():
         if len(clade_snps) == 0:
@@ -53,7 +53,16 @@ def get_node_path_scores(
     snps: SnpResults,
     scoring_function: Callable[[CladeMatchInfo], float],
 ) -> dict[CladeName, float]:
-    """Get the score for a single node."""
+    """Get the score for a single node's path (from the root to the node).
+
+    Args:
+        tree: The YTreeData object.
+        node: The ID of the node to score.
+        snps: The SnpResults to use for scoring.
+        scoring_function: The scoring function to use.
+
+    The scoring function should take a CladeMatchInfo object and return a number.
+    """
     scores = {}
     for ancestor_node in nx.ancestors(tree.graph, node):
         match_info = get_node_match_info(tree=tree, node=ancestor_node, snps=snps)
@@ -69,7 +78,10 @@ def simple_scoring_function(match_info: CladeMatchInfo) -> float:
 
 
 def get_ordered_clade_details(tree: YTreeData, snps: SnpResults) -> list[CladeInfo]:
-    """Get an ordered list of clades with their match info."""
+    """Get an ordered list of clades with their match info.
+
+    The first clade in the list is the best match.
+    """
     candidates = find_nodes_with_positive_matches(tree=tree, snps=snps)
     candidate_scores = {}
     for node in candidates:
diff --git a/yclade/snps.py b/yclade/snps.py
index 7b8a76b..702ac04 100644
--- a/yclade/snps.py
+++ b/yclade/snps.py
@@ -4,7 +4,15 @@
 
 
 def parse_snp_results(snp_string: str) -> SnpResults:
-    """Parse a string of comma separate SNPs into SnpResults."""
+    """Parse a string of comma separated SNPs into SnpResults.
+
+    Args:
+        snp_string: A string of comma separated SNPs.
+
+    The SNPs can be separated by commas and, optionally, spaces.
+    All SNPs must have the form snp+ (for a positively tested SNP)
+    or snp- (for a negatively tested SNP), otherwise they are ignored.
+    """
     snps = [snp.strip() for snp in snp_string.split(",")]
     positive_snps = {snp.rstrip("+") for snp in snps if snp.endswith("+")}
     negative_snps = {snp.rstrip("-") for snp in snps if snp.endswith("-")}