docs,s+: add api documentation and update docstrings

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
+surplus version 2.0.0
-```
+Thomson Plaza
-
+301 Upper Thomson Road
-```python
+Sin Ming, Bishan
->>> from surplus import surplus, Localcode
+574408
->>> Localcode(code="8RPQ+JW", locality="Singapore").full_length()
+Central, Singapore
-TODO API DEMO
 ```
 
 ## 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},
+  -c {pluscode,localcode,latlong,sharetext},
-  --convert-to {pluscode,localcode,latlong,shareabletext}
+  --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
 

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:
+        def some_operation(path) -> Result[str]:
-            file_contents = Path(...).read_text()
+            try:
-        except Exception as exc:
+                file = open(path)
-            # must pass a default value
+                contents = file.read()
-            result = Result[str]("", error=exc)
-        else:
-            result = Result[str](file_contents)
 
-        # handle result
+            except Exception as exc:
-        if not result:
+                # must pass a default value
-            # .cry() either raises an exception or returns an error message
+                result = Result[str]("", error=exc)
-            error_message = result.cry()
+
+            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
+    typing.NamedTuple representing a shortened Plus Code with locality, referred to by
-    to by surplus as a "local code"
+    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
+            original user-passed query string or a list of strings from splitting
-            list[str]: original user-passed query string split by spaces
+            user-passed query string by spaces
-        geocoder: Callable[[str], Latlong] = default_geocoder
+        geocoder: Callable[[str], Latlong] = default_geocoderi
-            name string to location function, must take in a string and return a Latlong.
+            name string to location function, must take in a string and return a Latlong,
-            exceptions are handled by the caller.
+            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
+            are placed top-level in the dict, exceptions are handled by the caller.
-            the playground notebook for example output.
+            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(
+def parse_query(behaviour: Behaviour) -> Result[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(
+def surplus(query: Query | str, behaviour: Behaviour) -> Result[str]:
-    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
+        query object to convert or string to attempt to query for then convert
-               each type of query object
-        str: string to attempt to query for
     behaviour: Behaviour
-        program behaviour namedtuple
+        surplus behaviour namedtuple
 
     returns Result[str]
     """