docs: fix and improve docstrings

Resolves: #68
danielnsilva · Jun 1, 2024 · ed16999 · ed16999
1 parent a356077
commit ed16999
Show file tree

Hide file tree

Showing 5 changed files with 56 additions and 28 deletions.
diff --git a/semanticscholar/PaginatedResults.py b/semanticscholar/PaginatedResults.py
@@ -10,8 +10,6 @@ class PaginatedResults:
     '''
     Base class that abstracts paginated results from API search.
     You can just iterate over results regardless of the number of pages.
-    PaginatedResults and AsyncPaginatedResults inherit from this class, 
-    with minor adjustments.
     '''
 
     def __init__(
@@ -62,35 +60,51 @@ async def create(
     @property
     def total(self) -> int:
         '''
+        Represents the total number of results in the query across all pages.
+        From the official docs: "Because of the subtleties of finding partial
+        phrase matches in different parts of the document, be cautious about
+        interpreting the total field as a count of documents containing any
+        particular word in the query."
+
         :type: :class:`int`
         '''
         return self._total
 
     @property
     def offset(self) -> int:
         '''
+        The position of the first item in the current page.
+
         :type: :class:`int`
         '''
         return self._offset
 
     @property
     def next(self) -> int:
         '''
+        The position of the first item in the next page.
+
         :type: :class:`int`
         '''
         return self._next
 
     @property
     def items(self) -> list:
         '''
+        Accumulated items across all fetched pages of results up to the
+        current page.
+
         :type: :class:`list`
         '''
         return self._items
 
     @property
-    def raw_data(self) -> list:
+    def raw_data(self) -> List[dict]:
         '''
-        :type: :class:`list`
+        The data from the current page of results in its original JSON
+        structure, represented as a `list` of `dict`.
+
+        :type: :class:`List` of :class:`dict`
         '''
         return self._data
 
@@ -177,7 +191,8 @@ def _update_params(self, results: Union[dict, List[dict]]) -> list:
 
     def next_page(self) -> None:
         '''
-        Get next results
+        Fetches the next page of results from the API and updates the current
+        items list.
         '''
         self._get_next_page()
 

diff --git a/semanticscholar/PublicationVenue.py b/semanticscholar/PublicationVenue.py
@@ -62,7 +62,7 @@ def type(self) -> str:
     @property
     def url(self) -> str:
         '''
-        :type: :class:`str
+        :type: :class:`str`
         '''
         return self._url
 

diff --git a/semanticscholar/SemanticScholar.py b/semanticscholar/SemanticScholar.py
@@ -93,8 +93,9 @@ def get_paper(
             ) -> Paper:
         '''Paper lookup
 
-        :calls: `GET /paper/{paper_id} <https://api.semanticscholar.org/\
-            api-docs/graph#tag/Paper-Data/operation/get_graph_get_paper>`_
+        :calls: `GET /graph/v1/paper/{paper_id} \
+            <https://api.semanticscholar.org/api-docs/graph#tag/Paper-Data\
+            /operation/get_graph_get_paper>`_
 
         :param str paper_id: S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL, \
                PMID, PMCID, or URL from:
@@ -129,8 +130,9 @@ def get_papers(
             ) -> Union[List[Paper], Tuple[List[Paper], List[str]]]:
         '''Get details for multiple papers at once
 
-        :calls: `POST /paper/batch <https://api.semanticscholar.org/api-docs/\
-            graph#tag/Paper-Data/operation/post_graph_get_papers>`_
+        calls: `POST /graph/v1/paper/batch \
+            <https://api.semanticscholar.org/api-docs/graph#tag/Paper-Data\
+            /operation/post_graph_get_papers>`_
 
         :param str paper_ids: list of IDs (must be <= 500) - S2PaperId,\
             CorpusId, DOI, ArXivId, MAG, ACL, PMID, PMCID, or URL from:
@@ -171,7 +173,7 @@ def get_paper_authors(
             ) -> PaginatedResults:
         '''Get details about a paper's authors
 
-        :calls: `POST /paper/{paper_id}/authors \
+        ::calls: `POST /graph/v1/paper/{paper_id}/authors \
             <https://api.semanticscholar.org/api-docs/graph#tag/Paper-Data\
             /operation/get_graph_get_paper_authors>`_
 
@@ -208,7 +210,7 @@ def get_paper_citations(
             ) -> PaginatedResults:
         '''Get details about a paper's citations
 
-        :calls: `POST /paper/{paper_id}/citations \
+        :calls: `POST /graph/v1/paper/{paper_id}/citations \
             <https://api.semanticscholar.org/api-docs/graph#tag/Paper-Data\
             /operation/get_graph_get_paper_citations>`_
 
@@ -245,7 +247,7 @@ def get_paper_references(
             ) -> PaginatedResults:
         '''Get details about a paper's references
 
-        :calls: `POST /paper/{paper_id}/references \
+        :calls: `POST /graph/v1/paper/{paper_id}/references \
             <https://api.semanticscholar.org/api-docs/graph#tag/Paper-Data\
             /operation/get_graph_get_paper_references>`_
 
@@ -296,10 +298,12 @@ def search_paper(
             Bulk retrieval instead returns up to 10,000,000 results (1,000 \
             in each page).
 
-        :calls: `GET /paper/search <https://api.semanticscholar.org/api-docs/\
-            graph#tag/Paper-Data/operation/get_graph_paper_relevance_search>`_
-        :calls: `GET /paper/search <https://api.semanticscholar.org/api-docs/\
-            graph#tag/Paper-Data/operation/get_graph_paper_bulk_search>`_
+        :calls: `GET /graph/v1/paper/search \
+            <https://api.semanticscholar.org/api-docs/graph#tag/Paper-Data\
+            /operation/get_graph_paper_relevance_search>`_
+        :calls: `GET /graph/v1/paper/search \
+            <https://api.semanticscholar.org/api-docs/graph#tag/Paper-Data\
+            /operation/get_graph_paper_bulk_search>`_
 
         :param str query: plain-text search query string.
         :param str year: (optional) restrict results to the given range of \
@@ -358,8 +362,9 @@ def get_author(
             ) -> Author:
         '''Author lookup
 
-        :calls: `GET /author/{author_id} <https://api.semanticscholar.org/\
-            api-docs/graph#tag/Author-Data/operation/get_graph_get_author>`_
+        :calls: `GET /graph/v1/author/{author_id} \
+            <https://api.semanticscholar.org/api-docs/graph#tag/Author-Data\
+            /operation/get_graph_get_author>`_
 
         :param str author_id: S2AuthorId.
         :returns: author data
@@ -385,8 +390,9 @@ def get_authors(
             ) -> Union[List[Author], Tuple[List[Author], List[str]]]:
         '''Get details for multiple authors at once
 
-        :calls: `POST /author/batch <https://api.semanticscholar.org/api-docs/\
-            graph#tag/Author-Data/operation/get_graph_get_author>`_
+        :calls: `POST /graph/v1/author/batch \
+            <https://api.semanticscholar.org/api-docs/graph#tag/Author-Data\
+            /operation/get_graph_get_author>`_
 
         :param str author_ids: list of S2AuthorId (must be <= 1000).
         :returns: author data, and optionally list of IDs not found.
@@ -416,7 +422,7 @@ def get_author_papers(
             ) -> PaginatedResults:
         '''Get details about a author's papers
 
-        :calls: `POST /paper/{author_id}/papers \
+        :calls: `POST /graph/v1/paper/{author_id}/papers \
             <https://api.semanticscholar.org/api-docs/graph#tag/Paper-Data\
             /operation/get_graph_get_author_papers>`_
 
@@ -453,8 +459,9 @@ def search_author(
             ) -> PaginatedResults:
         '''Search for authors by name
 
-        :calls: `GET /author/search <https://api.semanticscholar.org/api-docs/\
-            graph#tag/Author-Data/operation/get_graph_get_author_search>`_
+        :calls: `GET /graph/v1/author/search \
+            <https://api.semanticscholar.org/api-docs/graph#tag/Author-Data\
+            /operation/get_graph_get_author_search>`_
 
         :param str query: plain-text search query string.
         :param list fields: (optional) list of the fields to be returned.

diff --git a/semanticscholar/SemanticScholarObject.py b/semanticscholar/SemanticScholarObject.py
@@ -18,12 +18,20 @@ def __repr__(self) -> Any:
     def __getitem__(self, key) -> Any:
         return self._data.__getitem__(key)
 
-    def keys(self):
+    def keys(self) -> list:
+        '''
+        Returns a list of all keys in the API response data.
+
+        :rtype: :class:`list`
+        '''
         return self._data.keys()
 
     @property
     def raw_data(self) -> dict:
         '''
+        The API response data in its original JSON structure,
+        represented as a `dict`.
+
         :type: :class:`dict`
         '''
         return self._data
diff --git a/semanticscholar/Tldr.py b/semanticscholar/Tldr.py
@@ -1,5 +1,3 @@
-from typing import Any
-
 from semanticscholar.SemanticScholarObject import SemanticScholarObject
 
 
@@ -18,7 +16,7 @@ def __init__(self, data) -> None:
     @property
     def model(self) -> str:
         '''
-        :type :class:`str`
+        :type: :class:`str`
         '''
         return self._model