From a61a80d8c12400d395c1c363cf2cadbf42fadcf9 Mon Sep 17 00:00:00 2001
From: Mark Joshwel <mark@joshwel.co>
Date: Sat, 3 Jun 2023 08:31:02 +0000
Subject: [PATCH] docs: many (#1)

- fix/update table of contents
- add api reference
- add wrong format contrib guide
- update usage and examples
---
 README.md | 159 ++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 149 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 97a9006..63c49c3 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,18 @@
 # surplus
 
-plus code to iOS-Shortcuts-like shareable text
+Plus Code to iOS-Shortcuts-like shareable text
 
-- Installing
-- Usage
-- Licence
+- [Installing](#installing)
+- [Usage](#usage)
+  - [Command-line Interface](#command-line-interface)
+  - [API Reference](#api-reference)
+    - [surplus.surplus()](#surplussurplus)
+    - [surplus.parse_query()](#surplusparse_query)
+    - [surplus.Localcode](#surpluslocalcode)
+    - [surplus.Latlong](#surpluslatlong)
+- [Developing](#developing)
+- [The format is wrong/different!](#the-format-is-wrongdifferent)
+- [Licence](#licence)
 
 ```text
 $ surplus 6PH59R3J+R9
@@ -16,8 +24,10 @@ Singapore
 ```
 
 ```python
->>> import surplus
->>> surplus.surplus("6PH58RPQ+JW")
+>>> from surplus import surplus, Localcode
+>>> Localcode(code="8RPQ+JW", locality="Singapore").full_length()
+(True, '6PH58RPQ+JW')
+>>> surplus("6PH58RPQ+JW")
 (True, 'Caldecott Stn Exit 4\nToa Payoh Link\n298106\nSingapore')
 ```
 
@@ -31,19 +41,135 @@ pip install git+https://github.com/markjoshwel/surplus
 
 ## Usage
 
-```text
-usage: surplus [-h] [-d] pluscode
+### Command-line Interface
 
-plus code to iOS-Shortcuts-like shareable text
+```text
+usage: surplus [-h] [-d] query
+
+Plus Code to iOS-Shortcuts-like shareable text
 
 positional arguments:
-  pluscode     full-length plus code including area code, e.g.: 6PH58QMF+FX
+  query        full-length Plus Code (6PH58QMF+FX), local codes (8QMF+FX Singapore), or latlong (1.3336875, 103.7749375)
 
 options:
   -h, --help   show this help message and exit
   -d, --debug  prints lat, long and reverser response dict to stderr
 ```
 
+### API Reference
+
+#### `surplus.surplus()`
+
+pluscode to shareable text conversion function
+
+- signature  
+
+  ```python
+  def surplus(
+      query: str | Localcode | Latlong,
+      reverser: Callable = Nominatim(user_agent="surplus").reverse,
+      debug: bool = False,
+  ) -> tuple[bool, str]:
+    ...
+  ```
+
+- arguments
+
+  - `query: str | surplus.Localcode | surplus.Latlong`  
+      str - normal longcode (6PH58QMF+FX)
+      surplus.Localcode - shortcode with locality (8QMF+FX Singapore)
+      surplus.Latlong - latlong
+
+  - `reverser: Callable = geopy.geocoders.Nominatim(user_agent="surplus").reverser`  
+      latlong to data function, accesses a dict from .raw attribute of return object
+      function should be able to take a string with two floats
+
+      ```python
+      # code used by surplus
+      location: dict[str, Any] = reverser(f"{lat}, {lon}").raw
+      ```
+
+      dict should be similar to geopy's geocoder provider .raw dicts
+
+  - `debug: bool = False`  
+      prints lat, long and reverser response dict to stderr
+
+- returns `tuple[bool, str]`  
+
+  - `(True, <str>)`  
+      conversion was successful, str is resultant text  
+  - `(False, <str>)`  
+      conversion failed, str is error message
+
+---
+
+#### `surplus.parse_query()`
+
+function that parses a string Plus Code, local code or latlong into a str, surplus.Localcode or surplus.Latlong respectively
+
+- signature:
+
+    ```python
+    def parse_query(query: str) -> tuple[bool, str | Localcode | Latlong]:
+    ```
+  
+- arguments:
+
+  - `query: str`  
+    string Plus Code, local code or latlong
+
+- returns `tuple[bool, str | Localcode | Latlong]`
+
+  - `(True, <str | Localcode | Latlong>)`  
+      conversion was successful, second element is result
+  - `(False, <str>)`  
+      conversion failed, str is error message
+
+---
+
+#### `surplus.Localcode`
+
+`typing.NamedTuple` representing short Plus Code with locality
+
+- parameters:
+
+  - `code: str`
+      Plus Code - e.g.: "8QMF+FX"
+  - `locality: str`
+      e.g.: "Singapore"
+
+---
+
+##### `surplus.Localcode.full_length()`
+
+method that calculates full-length Plus Code using locality
+
+- signature:
+
+    ```python
+    def full_length(self) -> tuple[bool, str]:
+    ```
+
+- returns:
+
+  - `(True, <str>)`  
+      conversion was successful, str is resultant Plus Code  
+  - `(False, <str>)`  
+      conversion failed, str is error message
+
+---
+
+#### `surplus.Latlong`
+
+`typing.NamedTuple` representing a pair of latitude and longitude coordinates
+
+- parameters:
+
+  - `lat: float`  
+      latitudinal coordinate
+  - `long: float`  
+      longitudinal coordinate
+
 ## Developing
 
 Prerequisites:
@@ -59,6 +185,19 @@ poetry install
 poetry shell
 ```
 
+## The format is wrong/different!
+
+If surplus generates wrong text for a particular Plus Code,
+[submit an issue](https://github.com/markjoshwel/surplus/issues/new). 
+
+Ensure you detail the following:
+
+1. The erroneous Plus Code, local code or latlong, or a similar coordinate that reproduces the same error
+
+2. Output from the terminal, with `--debug` enabled or `debug=True`
+
+3. How it should look like instead
+
 ## Licence
 
 surplus is free and unencumbered software released into the public domain.