update documentation

README.md

@@ -4,7 +4,9 @@
 
 [Pydantic](https://pydantic-docs.helpmanual.io/) models for the [Reasoner API](https://github.com/NCATS-Tangerine/NCATS-ReasonerStdAPI) data formats.
 
-These models are very handy when setting up a Reasoner API with [FastAPI](https://fastapi.tiangolo.com/).
+These models are very handy when setting up a Reasoner API with [FastAPI](https://fastapi.tiangolo.com/). 
+
+These models provide validation for TRAPI messages, as well as useful utilities based on architectural decisions, such as edge merging, result merging, and analysis combination. 
 
 ## Example usage
 

reasoner_pydantic/message.py

@@ -69,6 +69,8 @@ def parse_obj(obj, normalize=True):
         return m
 
     def update(self, other: "Message", normalize=True):
+        """Updates one message with information from another.
+        Can run with normalize=false, if both messages are normalized already."""
         if hash(self.query_graph) != hash(other.query_graph):
             raise NotImplementedError("Query graph merging not supported yet")
         # Make a copy because normalization will modify results

reasoner_pydantic/results.py

@@ -147,6 +147,8 @@ def parse_obj(obj):
         return result
 
     def combine_analyses_by_resource_id(self):
+        # Useful when a service unintentionally adds multiple analyses to a single result
+        # Combines all of those analyses
         combine = HashableMapping[str, Analysis]()
         analyses = HashableSequence.parse_obj([analysis for analysis in self.analyses])
         for i, analysis in enumerate(analyses):

reasoner_pydantic/shared.py

@@ -40,8 +40,9 @@ class EdgeIdentifier(str):
 
 
 class RecursiveAttribute(BaseModel):
-    """Attribute subattribute."""
+    """Recursive Attribute subattribute."""
 
+    # Included to preserve direct references to Attribute and SubAttribute
     attribute_type_id: CURIE = Field(..., title="type")
     value: Any = Field(..., title="value")
     value_type_id: Optional[CURIE] = Field(