docs,s+: add api documentation and update docstrings

2023-09-02 20:05:37 +00:00 · 2023-09-02 20:05:37 +00:00 · 35f19b8bc9
parent 6591d9f476
commit 35f19b8bc9
2 changed files with 652 additions and 63 deletions
--- a/README.md
+++ b/README.md
@ -18,25 +18,26 @@ surplus is a Python script to convert
 to iOS Shortcuts-like shareable text.

 - [installation](#installation)
- [command-line usage](#command-line-usaage)
+- [usage](#usage)
+  - [command-line usage](#command-line-usaage)
+  - [example api usage](#example-api-usage)
 - [developer's guide](#developers-guide)
-  - [api reference](#api-reference)
 - [contributor's guide](#contributors-guide)
  - [reporting incorrect output](#reporting-incorrect-output)
    - [the reporting process](#the-reporting-process)
    - [what counts as "incorrect"](#what-counts-as-incorrect)
 - [output technical details](#the-technical-details-of-surpluss-output)
+- [api reference](#api-reference)
 - [licence](#licence)

 ```text
 $ surplus 9R3J+R9 Singapore
-TODO CLI DEMO
-```
-
-```python
->>> from surplus import surplus, Localcode
->>> Localcode(code="8RPQ+JW", locality="Singapore").full_length()
-TODO API DEMO
+surplus version 2.0.0
+Thomson Plaza
+301 Upper Thomson Road
+Sin Ming, Bishan
+574408
+Central, Singapore
 ```

 ## installation
@ -51,7 +52,9 @@ install surplus directly from the repository using pip:
 pip install git+https://github.com/markjoshwel/surplus.git@future
 ```

-## command-line usage
+## usage
+
+### command-line usage

 ```text
 usage: surplus [-h] [-d] [-v] [-c {pluscode,localcode,latlong,string}]
@ -70,12 +73,57 @@ options:
  -d, --debug           prints lat, long and reverser response dict to
                        stderr
  -v, --version         prints version information to stderr and exits
-  -c {pluscode,localcode,latlong,shareabletext},
-  --convert-to {pluscode,localcode,latlong,shareabletext}
+  -c {pluscode,localcode,latlong,sharetext},
+  --convert-to {pluscode,localcode,latlong,sharetext}
                        converts query a specific output type, defaults
-                        to 'shareabletext'
+                        to 'sharetext'
 ```

+### example api usage
+
+here are a few examples to get you quickly started using surplus in your own program:
+
+1. let surplus do the heavy lifiting
+
+   ```python
+   >>> from surplus import surplus, Behaviour
+   >>> result = surplus("Ngee Ann Polytechnic, Singapore", Behaviour())
+   >>> result.get()
+   'Ngee Ann Polytechnic\n535 Clementi Road\nBukit Timah\n599489\nNorthwest, Singapore'
+   ```
+
+2. handle queries seperately
+
+  ```python
+  >>> import surplus
+  >>> behaviour = surplus.Behaviour("6PH58R3M+F8")
+  >>> query = surplus.parse_query(behaviour)
+  >>> result = surplus.surplus(query.get(), behaviour)
+  >>> result.get()
+  'MacRitchie Nature Trail\nCentral Water Catchment\n574325\nCentral, Singapore'
+  ```
+
+3. start from a Query object
+
+   ```python
+   >>> import surplus
+   >>> localcode = surplus.LocalCodeQuery(code="8R3M+F8", locality="Singapore")
+   >>> pluscode_str = localcode.to_full_plus_code(geocoder=surplus.default_geocoder).get()
+   >>> pluscode = surplus.PlusCodeQuery(pluscode_str)
+   >>> result = surplus.surplus(pluscode, surplus.Behaviour())
+   >>> result.get()
+   'Wisma Atria\n435 Orchard Road\n238877\nCentral, Singapore'
+   ```
+
+notes:
+
+- you can change what surplus does by passing in a custom `Behaviour` object.
+
+- most surplus functions return a `Result` object. while you can `.get()` the Result to
+  obtain the proper return value, this is dangerous and might raise an exception.
+
+see the [api reference](#api-reference) for more information.
+
 ## developer's guide

 prerequisites:
@ -91,6 +139,8 @@ poetry install
 poetry shell
 ```

+for information on surplus's exposed api, see the [api reference](#api-reference).
+
 ## contributor's guide

 1. fork the repository and branch off from the `future` branch
@ -203,6 +253,10 @@ of incorrect outputs.

 ## the technical details of surplus's output

+> **Note**  
+> this is a breakdown of surplus's output when converting to shareable text.
+> when converting to other output types, n
+
 ```
 $ s+ --debug 8QJF+RP Singapore
 surplus version 2.0.0, debug mode
@ -256,7 +310,7 @@ variables

  represents the plus code and locality portions of a
  [shortened plus code](https://en.wikipedia.org/wiki/Open_Location_Code#Common_usage_and_shortening)
-  (_referred to as a "short/local code" in the codebase_) respectively.
+  (_referred to as a "local code" in the codebase_) respectively.

 - **variable `query`**

@ -458,7 +512,534 @@ breakdown of each output line, accompanied by their nominatim key:

 ## api reference

-TODO API REF
+- [constants](#constants)
+- [exception classes](#exception-classes)
+- [types](#types)
+- [`class Behaviour`](#class-behaviour)
+- [`class ConversionResultTypeEnum`](#class-conversionresulttypeenum)
+- [`class Result`](#class-result)
+  - [`Result.__bool__()`](#result__bool__)
+  - [`Result.cry()`](#resultcry)
+  - [`Result.get()`](#resultget)
+- [`class Latlong`](#class-latlong)
+- [`class PlusCodeQuery`](#class-pluscodequery)
+- [`class LocalCodeQuery`](#class-localcodequery)
+- [`class LatlongQuery`](#class-latlongquery)
+- [`class StringQuery`](#class-stringquery)
+- [`def surplus()`](#def-surplus)
+- [`def parse_query()`](#def-parse_query)
+- [`def default_geocoder()`](#def-default_geocoder)
+- [`def default_reverser()`](#def-default_reverser)
+
+### constants
+
+- `VERSION: tuple[int, int, int]`
+
+  a tuple of integers representing the version of surplus, in the format
+  `[major, minor, patch]`
+
+- `SHAREABLE_TEXT_LINE_0_KEYS: tuple[str, ...]`  
+  `SHAREABLE_TEXT_LINE_1_KEYS: tuple[str, ...]`  
+  `SHAREABLE_TEXT_LINE_2_KEYS: tuple[str, ...]`  
+  `SHAREABLE_TEXT_LINE_3_KEYS: tuple[str, ...]`  
+  `SHAREABLE_TEXT_LINE_4_KEYS: tuple[str, ...]`  
+  `SHAREABLE_TEXT_LINE_5_KEYS: tuple[str, ...]`  
+  `SHAREABLE_TEXT_LINE_6_KEYS: tuple[str, ...]`  
+
+  a tuple of strings containing nominatim keys used in shareable text line 0-6
+
+- `SHAREABLE_TEXT_NAMES: tuple[str, ...]`
+  
+  a tuple of strings containing nominatim keys used in shareable text line 0-2 and
+  special keys in line 3
+
+- `EMPTY_LATLONG: Latlong`  
+  a constant for an empty latlong coordinate, with latitude and longitude set to 0.0
+
+### exception classes
+
+- `class SurplusException(Exception)`  
+  base skeleton exception for handling and typing surplus exception classes
+- `class NoSuitableLocationError(SurplusException)`
+- `class IncompletePlusCodeError(SurplusException)`
+- `class PlusCodeNotFoundError(SurplusException)`
+- `class LatlongParseError(SurplusException)`
+- `class EmptyQueryError(SurplusException)`
+- `class UnavailableFeatureError(SurplusException)`
+
+### types
+
+#### `Query`
+
+```python
+Query: typing.TypeAlias = PlusCodeQuery | LocalCodeQuery | LatlongQuery | StringQuery
+```
+
+[type alias](https://docs.python.org/3/library/typing.html#type-aliases) representing
+either a
+[`PlusCodeQuery`](#class-pluscodequery),
+[`LocalCodeQuery`](#class-localcodequery),
+[`LatlongQuery`](#class-latlongquery) or
+[`StringQuery`](#class-stringquery)
+
+#### `ResultType`
+
+```python
+ResultType = TypeVar("ResultType")
+```
+
+[generic type](https://docs.python.org/3/library/typing.html#generics) used by
+[`Result`](#class-result)
+
+### `class Behaviour`
+
+[`typing.NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple) 
+representing how surplus operations should behave
+
+attributes
+
+- `query: str | list[str] = ""`  
+  original user-passed query string or a list of strings from splitting user-passed query 
+  string by spaces
+
+- `geocoder: typing.Callable[[str], Latlong] = default_geocoder`  
+  name string to location function, must take in a string and return a
+  [`Latlong`](#class-latlong), exceptions are handled by the caller
+
+- `reverser: Callable[[Latlong], dict[str, Any]] = default_reverser`  
+  [`Latlong`] object to dictionary function, must take in a string and return a dict. 
+  keys found in SHAREABLE_TEXT_LINE_*_KEYS used to access address details are placed 
+  top-level in the dict, exceptions are handled by the caller.
+  see the [playground notebook](playground.ipynb) for example output
+
+- `stderr: typing.TextIO = sys.stderr`  
+  [TextIO-like object](https://docs.python.org/3/library/io.html#text-i-o)
+  representing a writeable file.
+  defaults to [`sys.stderr`](https://docs.python.org/3/library/sys.html#sys.stderr).
+
+- `stdout: typing.TextIO = sys.stdout`  
+  [TextIO-like object](https://docs.python.org/3/library/io.html#text-i-o)
+  representing a writeable file.
+  defaults to [`sys.stdout`](https://docs.python.org/3/library/sys.html#sys.stdout).
+
+- `debug: bool = False`  
+  whether to print debug information to stderr
+
+- `version_header: bool = False`  
+  whether to print version information and exit
+
+- `convert_to_type: ConversionResultTypeEnum = ConversionResultTypeEnum.SHAREABLE_TEXT`  
+  what type to convert the query to
+
+### `class ConversionResultTypeEnum`
+
+[enum.Enum](https://docs.python.org/3/library/enum.html)
+representing what the result type of conversion should be
+
+values
+
+- `PLUS_CODE: str = "pluscode"`
+- `LOCAL_CODE: str = "localcode"`
+- `LATLONG: str = "latlong"`
+- `SHAREABLE_TEXT: str = "sharetext"`
+
+### `class Result`
+
+[`typing.NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple) 
+representing the result for safe value retrieval
+
+attributes
+
+- `value: ResultType`  
+  value to return or fallback value if erroneous
+
+- `error: BaseException | None = None`  
+  exception if any
+
+example usage
+
+```python
+# do something
+def some_operation(path) -> Result[str]:
+    try:
+        file = open(path)
+        contents = file.read()
+
+    except Exception as exc:
+        # must pass a default value
+        result = Result[str]("", error=exc)
+
+    else:
+        result = Result[str](contents)
+
+# call function and handle result
+result = some_operation("some_file.txt")
+
+if not result:  # check if the result is erroneous
+    # .cry() raises the exception
+    # (or returns it as a string error message using string=True)
+    result.cry()
+    ...
+
+else:
+    # .get() raises exception or returns value,
+    # but since we checked for errors this is safe
+    print(result.get())
+```
+
+methods
+
+- [`def __bool__(self) -> bool: ...`](#result__bool__)
+- [`def get(self) -> ResultType: ...`](#resultcry)
+- [`def cry(self, string: bool = False) -> str: ...`](#resultget)
+
+#### `Result.__bool__()`
+
+method that returns `True` if `self.error` is not `None`
+
+- signature
+
+  ```python
+  def __bool__(self) -> bool: ...
+  ```
+
+- returns `bool`
+
+#### `Result.cry()`
+
+method that raises `self.error` if is an instance of `BaseException`, returns
+`self.error` if is an instance of str, or returns an empty string if `self.error` is None
+
+- signature
+
+  ```python
+  def cry(self, string: bool = False) -> str: ...
+  ```
+
+- arguments
+
+  - `string: bool = False`  
+    if `self.error` is an Exception, returns it as a string error message
+
+- returns `str`
+
+#### `Result.get()`
+
+method that returns `self.value` if Result is non-erroneous else raises error
+
+- signature
+
+  ```python
+  def get(self) -> ResultType: ...
+  ```
+
+- returns `self.value`
+
+### `class Latlong`
+
+[`typing.NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple) 
+representing a latitude-longitude coordinate pair
+
+attributes
+
+- `latitude: float`
+- `longitude: float`
+
+methods
+
+- [`def __str__(self) -> str: ...`](#latlong__str__)
+
+#### `Latlong.__str__()`
+
+method that returns a comma-and-space-seperated string of `self.latitude` and
+`self.longitude`
+
+- signature
+
+  ```python
+  def __str__(self) -> str: ...
+  ```
+
+- returns `str`
+
+### `class PlusCodeQuery`
+
+[`typing.NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple) 
+representing a full-length Plus Code (e.g., 6PH58QMF+FX)
+
+attributes
+
+- `code: str`
+
+methods
+
+- [`def to_lat_long_coord(self, ...) -> Result[Latlong]: ...`](#pluscodequeryto_lat_long_coord)
+- [`def __str__(self) -> str: ...`](#pluscodequery__str__)
+
+#### `PlusCodeQuery.to_lat_long_coord()`
+
+- signature
+
+  ```python
+  def to_lat_long_coord(self, geocoder: Callable[[str], Latlong]) -> Result[Latlong]:
+      ...
+  ```
+
+- arguments
+
+  - `geocoder: typing.Callable[[str], Latlong]`  
+    name string to location function, must take in a string and return a
+    [`Latlong`](#class-latlong), exceptions are handled by the caller
+
+- returns [`Result`](#class-result)[`[Latlong]`](#class-latlong)
+
+#### `PlusCodeQuery.__str__()`
+
+method that returns string representation of query
+
+- signature
+
+  ```python
+  def __str__(self) -> str: ...
+  ```
+
+- returns `str`
+
+### `class LocalCodeQuery`
+
+[`typing.NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple) 
+representing a
+[shortened Plus Code](https://en.wikipedia.org/wiki/Open_Location_Code#Common_usage_and_shortening)
+with locality, referred to by surplus as a "local code"
+
+attributes
+
+- `code: str`  
+  Plus Code portion of local code, e.g., "8QMF+FX"
+
+- `locality: str`  
+  remaining string of local code, e.g., "Singapore"
+
+methods
+
+- [`def to_full_plus_code(self, ...) -> Result[str]: ...`](#localcodequeryto_full_plus_code)
+- [`def to_lat_long_coord(self, ...) -> Result[Latlong]: ...`](#localcodequeryto_lat_long_coord)
+- [`def __str__(self) -> str: ...`](#localcodequery__str__)
+
+#### `LocalCodeQuery.to_full_plus_code()`
+
+exclusive method that returns a full-length Plus Code as a string
+
+- signature
+
+  ```python
+  def to_full_plus_code(self, geocoder: Callable[[str], Latlong]) -> Result[str]:
+      ...
+  ```
+
+- arguments
+
+  - `geocoder: typing.Callable[[str], Latlong]`  
+    name string to location function, must take in a string and return a
+    [`Latlong`](#class-latlong), exceptions are handled by the caller
+
+- returns [`Result`](#class-result)`[str]`
+
+#### `LocalCodeQuery.to_lat_long_coord()`
+
+method that returns a latitude-longitude coordinate pair
+
+- signature
+
+  ```python
+  def to_lat_long_coord(self, geocoder: Callable[[str], Latlong]) -> Result[Latlong]:
+      ...
+  ```
+
+- arguments
+
+  - `geocoder: typing.Callable[[str], Latlong]`  
+    name string to location function, must take in a string and return a
+    [`Latlong`](#class-latlong), exceptions are handled by the caller
+
+- returns [`Result`](#class-result)[`[Latlong]`](#class-latlong)
+
+#### `LocalCodeQuery.__str__()`
+
+method that returns string representation of query
+
+- signature
+
+  ```python
+  def __str__(self) -> str: ...
+  ```
+
+- returns `str`
+
+### `class LatlongQuery`
+
+[`typing.NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple) 
+representing a latitude-longitude coordinate pair
+
+attributes
+
+- `latlong: Latlong`
+
+methods
+
+- [`def to_lat_long_coord(self, ...) -> Result[Latlong]: ...`](#latlongqueryto_lat_long_coord)
+- [`def __str__(self) -> str: ...`](#latlongquery__str__)
+
+#### `LatlongQuery.to_lat_long_coord()`
+
+method that returns a latitude-longitude coordinate pair
+
+- signature
+
+  ```python
+  def to_lat_long_coord(self, geocoder: Callable[[str], Latlong]) -> Result[Latlong]:
+      ...
+  ```
+
+- arguments
+
+  - `geocoder: typing.Callable[[str], Latlong]`  
+    name string to location function, must take in a string and return a
+    [`Latlong`](#class-latlong), exceptions are handled by the caller
+
+- returns [`Result`](#class-result)[`[Latlong]`](#class-latlong)
+
+#### `LatlongQuery.__str__()`
+
+method that returns string representation of query
+
+- signature
+
+  ```python
+  def __str__(self) -> str: ...
+  ```
+
+- returns `str`
+
+### `class StringQuery`
+
+[`typing.NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple) 
+representing a pure string query
+
+attributes
+
+- `query: str`
+
+methods
+
+- [`def to_lat_long_coord(self, ...) -> Result[Latlong]: ...`](#latlongqueryto_lat_long_coord)
+- [`def __str__(self) -> str: ...`](#latlongquery__str__)
+
+#### `LatlongQuery.to_lat_long_coord()`
+
+method that returns a latitude-longitude coordinate pair
+
+- signature
+
+  ```python
+  def to_lat_long_coord(self, geocoder: Callable[[str], Latlong]) -> Result[Latlong]:
+      ...
+  ```
+
+- arguments
+
+  - `geocoder: typing.Callable[[str], Latlong]`  
+    name string to location function, must take in a string and return a
+    [`Latlong`](#class-latlong), exceptions are handled by the caller
+
+- returns [`Result`](#class-result)[`[Latlong]`](#class-latlong)
+
+#### `LatlongQuery.__str__()`
+
+method that returns string representation of query
+
+- signature
+
+  ```python
+  def __str__(self) -> str: ...
+  ```
+
+- returns `str`
+
+### `def surplus()`
+
+query to shareable text conversion function
+
+- signature
+
+  ```python
+  def surplus(query: Query | str, behaviour: Behaviour) -> Result[str]: ..
+  ```
+
+- arguments
+
+  - `query: str | Query`  
+    [query object](#query) to convert or string to attempt to query for then convert
+
+  - `behaviour: Behaviour`  
+    [surplus behaviour namedtuple](#class-behaviour)
+
+- returns [`Result`](#class-result)`[str]`
+
+### `def parse_query()`
+
+function that parses a query string into a query object
+
+- signature
+
+  ```python
+  def parse_query(behaviour: Behaviour) -> Result[Query]: ...
+  ```
+
+- arguments
+
+  - `behaviour: Behaviour`  
+    [surplus behaviour namedtuple](#class-behaviour)
+
+- returns [`Result`](#class-result)[`[Query]`](#query)
+
+### `def default_geocoder()`
+
+default geocoder for surplus, uses OpenStreetMap Nominatim
+
+> **Note**  
+> function is not used by surplus and not directly by the user, but is exposed for
+> convenience
+>
+> pass in a custom function to [Behaviour](#class-behaviour) to override the default 
+> reverser
+>
+> see [Behaviour](#class-behaviour) for more information on what the function does
+
+- signature
+
+  ```python
+  def default_geocoder(place: str) -> Latlong:
+  ```
+
+### `def default_reverser()`
+
+default reverser for surplus, uses OpenStreetMap Nominatim
+
+> **Note**  
+> function is not used by surplus and not directly by the user, but is exposed for
+> convenience
+>
+> pass in a custom function to [Behaviour](#class-behaviour) to override the default 
+> reverser
+>
+> see [Behaviour](#class-behaviour) for more information on what the function does
+
+- signature
+
+  ```python
+  def default_reverser(latlong: Latlong) -> dict[str, Any]:
+  ```

 ## licence

--- a/surplus/surplus.py
+++ b/surplus/surplus.py
@ -178,7 +178,7 @@ ResultType = TypeVar("ResultType")

 class Result(NamedTuple, Generic[ResultType]):
    """
-    typing.NamedTuple representing a result for safe value handling
+    typing.NamedTuple representing a result for safe value retrieval

    arguments
        value: ResultType
@ -193,21 +193,31 @@ class Result(NamedTuple, Generic[ResultType]):

    example
        # do something
-        try:
-            file_contents = Path(...).read_text()
-        except Exception as exc:
-            # must pass a default value
-            result = Result[str]("", error=exc)
-        else:
-            result = Result[str](file_contents)
+        def some_operation(path) -> Result[str]:
+            try:
+                file = open(path)
+                contents = file.read()

-        # handle result
-        if not result:
-            # .cry() either raises an exception or returns an error message
-            error_message = result.cry()
+            except Exception as exc:
+                # must pass a default value
+                result = Result[str]("", error=exc)
+
+            else:
+                result = Result[str](contents)
+
+        # call function and handle result
+        result = some_operation("some_file.txt")
+
+        if not result:  # check if the result is erroneous
+            # .cry() raises the exception
+            # (or returns it as a string error message using string=True)
+            result.cry()
            ...
+
        else:
-            data = result.get()  # raises exception or returns value
+            # .get() raises exception or returns value,
+            # but since we checked for errors this is safe
+            print(result.get())
    """

    value: ResultType
@ -221,11 +231,11 @@ class Result(NamedTuple, Generic[ResultType]):
        """
        method that raises self.error if is an instance of BaseException,
        returns self.error if is an instance of str, or returns an empty string if
-        self.error is None.
+        self.error is None

        arguments
            string: bool = False
-                if self.error is an instance Exception, returns it as a string.
+                if self.error is an Exception, returns it as a string error message
        """

        if isinstance(self.error, BaseException):
@ -276,7 +286,7 @@ EMPTY_LATLONG: Final[Latlong] = Latlong(latitude=0.0, longitude=0.0)

 class PlusCodeQuery(NamedTuple):
    """
-    typing.NamedTuple representing a complete Plus Code
+    typing.NamedTuple representing a full-length Plus Code (e.g., 6PH58QMF+FX)

    arguments
        code: str
@ -295,7 +305,7 @@ class PlusCodeQuery(NamedTuple):
        arguments
            geocoder: typing.Callable[[str], Latlong]
                name string to location function, must take in a string and return a
-                Latlong. exceptions are handled.
+                Latlong, exceptions are handled by the caller

        returns Result[Latlong]
        """
@ -323,13 +333,14 @@ class PlusCodeQuery(NamedTuple):
        return Result[Latlong](Latlong(latitude=latitude, longitude=longitude))

    def __str__(self) -> str:
+        """method that returns string representation of query"""
        return f"{self.code}"


 class LocalCodeQuery(NamedTuple):
    """
-    typing.NamedTuple representing a complete shortened Plus Code with locality, referred
-    to by surplus as a "local code"
+    typing.NamedTuple representing a shortened Plus Code with locality, referred to by
+    surplus as a "local code"

    arguments
        code: str
@ -338,6 +349,7 @@ class LocalCodeQuery(NamedTuple):
            remaining string of local code, e.g., "Singapore"

    methods
+        def to_full_plus_code(self, ...) -> Result[str]: ...
        def to_lat_long_coord(self, ...) -> Result[Latlong]: ...
        def __str__(self) -> str: ...
    """
@ -347,12 +359,12 @@ class LocalCodeQuery(NamedTuple):

    def to_full_plus_code(self, geocoder: Callable[[str], Latlong]) -> Result[str]:
        """
-        method that returns a full-length Plus Code
+        exclusive method that returns a full-length Plus Code as a string

        arguments
            geocoder: typing.Callable[[str], Latlong]
                name string to location function, must take in a string and return a
-                Latlong. exceptions are handled.
+                Latlong, exceptions are handled by the caller

        returns Result[str]
        """
@ -378,7 +390,7 @@ class LocalCodeQuery(NamedTuple):
        arguments
            geocoder: typing.Callable[[str], Latlong]
                name string to location function, must take in a string and return a
-                Latlong. exceptions are handled.
+                Latlong, exceptions are handled by the caller

        returns Result[Latlong]
        """
@ -395,6 +407,7 @@ class LocalCodeQuery(NamedTuple):
        )

    def __str__(self) -> str:
+        """method that returns string representation of query"""
        return f"{self.code} {self.locality}"


@ -419,7 +432,7 @@ class LatlongQuery(NamedTuple):
        arguments
            geocoder: typing.Callable[[str], Latlong]
                name string to location function, must take in a string and return a
-                Latlong. exceptions are handled.
+                Latlong, exceptions are handled by the caller

        returns Result[Latlong]
        """
@ -427,15 +440,16 @@ class LatlongQuery(NamedTuple):
        return Result[Latlong](self.latlong)

    def __str__(self) -> str:
+        """method that returns string representation of query"""
        return f"{self.latlong.latitude}, {self.latlong.longitude}"


 class StringQuery(NamedTuple):
    """
-    typing.NamedTuple representing a complete Plus Code
+    typing.NamedTuple representing a pure string query

    arguments
-        code: str
+        query: str

    methods
        def to_lat_long_coord(self, ...) -> Result[Latlong]: ...
@ -451,7 +465,7 @@ class StringQuery(NamedTuple):
        arguments
            geocoder: typing.Callable[[str], Latlong]
                name string to location function, must take in a string and return a
-                Latlong. exceptions are handled.
+                Latlong, exceptions are handled by the caller

        returns Result[Latlong]
        """
@ -463,6 +477,7 @@ class StringQuery(NamedTuple):
            return Result[Latlong](EMPTY_LATLONG, error=exc)

    def __str__(self) -> str:
+        """method that returns string representation of query"""
        return self.query


@ -488,7 +503,7 @@ def default_geocoder(place: str) -> Latlong:


 def default_reverser(latlong: Latlong) -> dict[str, Any]:
-    """default geocoder for surplus, uses OpenStreetMap Nominatim"""
+    """default reverser for surplus, uses OpenStreetMap Nominatim"""
    location: _geopy_Location | None = _geopy_Nominatim(user_agent=USER_AGENT).reverse(
        str(latlong)
    )
@ -510,24 +525,24 @@ def default_reverser(latlong: Latlong) -> dict[str, Any]:

 class Behaviour(NamedTuple):
    """
-    typing.NamedTuple representing expected behaviour of surplus
+    typing.NamedTuple representing how surplus operations should behave

    arguments
        query: str | list[str] = ""
-            str: original user-passed query string
-            list[str]: original user-passed query string split by spaces
-        geocoder: Callable[[str], Latlong] = default_geocoder
-            name string to location function, must take in a string and return a Latlong.
-            exceptions are handled by the caller.
+            original user-passed query string or a list of strings from splitting
+            user-passed query string by spaces
+        geocoder: Callable[[str], Latlong] = default_geocoderi
+            name string to location function, must take in a string and return a Latlong,
+            exceptions are handled by the caller
        reverser: Callable[[str], dict[str, Any]] = default_reverser
            Latlong object to dictionary function, must take in a string and return a
            dict. keys found in SHAREABLE_TEXT_LINE_*_KEYS used to access address details
-            are placed top-level in the dict. exceptions are handled by the caller. see
-            the playground notebook for example output.
+            are placed top-level in the dict, exceptions are handled by the caller.
+            see the playground notebook for example output
        stderr: TextIO = stderr
-            TextIO-like object representing a writeable file. defaults to sys.stderr.
+            TextIO-like object representing a writeable file. defaults to sys.stderr
        stdout: TextIO = stdout
-            TextIO-like object representing a writeable file. defaults to sys.stdout.
+            TextIO-like object representing a writeable file. defaults to sys.stdout
        debug: bool = False
            whether to print debug information to stderr
        version_header: bool = False
@ -549,9 +564,7 @@ class Behaviour(NamedTuple):
 # functions


-def parse_query(
-    behaviour: Behaviour,
-) -> Result[Query]:
+def parse_query(behaviour: Behaviour) -> Result[Query]:
    """
    function that parses a query string into a query object

@ -928,19 +941,14 @@ def _generate_text(
    return "".join(_unique(text)).rstrip()


-def surplus(
-    query: Query | str,
-    behaviour: Behaviour,
-) -> Result[str]:
+def surplus(query: Query | str, behaviour: Behaviour) -> Result[str]:
    """
    query to shareable text conversion function

    query: Query | str
-        Query: query object to convert, see respective docstrings for more information on
-               each type of query object
-        str: string to attempt to query for
+        query object to convert or string to attempt to query for then convert
    behaviour: Behaviour
-        program behaviour namedtuple
+        surplus behaviour namedtuple

    returns Result[str]
    """