DOC: Updated documentation for get_entity_by_...

src/linkahead/utils/get_entity.py

@@ -30,7 +30,13 @@ from .escape import escape_squoted_text
 def get_entity_by_name(name: str, role: Optional[str] = None) -> Entity:
     """Return the result of a unique query that uses the name to find the correct entity.
 
-    Submits the query "FIND ENTITY WITH name='{name}'".
+Submits the query "FIND {role} WITH name='{name}'".
+
+Parameters
+----------
+
+role: str, optional
+  The role for the query, defaults to ``ENTITY``.
     """
     name = escape_squoted_text(name)
     if role is None:
@@ -42,7 +48,13 @@ def get_entity_by_name(name: str, role: Optional[str] = None) -> Entity:
 def get_entity_by_id(eid: Union[str, int], role: Optional[str] = None) -> Entity:
     """Return the result of a unique query that uses the id to find the correct entity.
 
-    Submits the query "FIND ENTITY WITH id='{eid}'".
+Submits the query "FIND {role} WITH id='{eid}'".
+
+Parameters
+----------
+
+role: str, optional
+  The role for the query, defaults to ``ENTITY``.
     """
     if role is None:
         role = "ENTITY"
@@ -53,7 +65,13 @@ def get_entity_by_id(eid: Union[str, int], role: Optional[str] = None) -> Entity
 def get_entity_by_path(path: str) -> Entity:
     """Return the result of a unique query that uses the path to find the correct file.
 
-    Submits the query "FIND FILE WHICH IS STORED AT '{path}'".
+Submits the query "FIND {role} WHICH IS STORED AT '{path}'".
+
+Parameters
+----------
+
+role: str, optional
+  The role for the query, defaults to ``ENTITY``.
     """
     # type hint can be ignored, it's a unique query
     return execute_query(f"FIND FILE WHICH IS STORED AT '{path}'", unique=True)  # type: ignore