doc: Minor updates to the API and usage documentation

broadworks_ocip/api.py

@@ -320,6 +320,12 @@ def authenticate(self) -> broadworks_ocip.base.OCICommand:
         """
         Authenticate the connection to the OCI-P server
 
+        This is typically not directly called by users, because the `command
+        ()` method checks, and if necessary, calls this method if the
+        connection is not already authenticated.   However if you are making
+        use of the API functions without using `command()` you may manually
+        authenticate yourself.
+
         Raises:
             OCIErrorResponse: An error was returned from the server
 
@@ -348,7 +354,18 @@ def authenticate(self) -> broadworks_ocip.base.OCICommand:
 
     def command(self, command, **kwargs) -> broadworks_ocip.base.OCICommand:
         """
-        Send a command and parameters to the server, receive and decode a response
+        Send a command and parameters to the server, receive and decode a
+        response. The command parameter is the name of Broadworks command - a
+        single word name of a `OCIRequest()` or `OCIResponse()`.  The
+        following parameters are the various arguments for that command.
+
+        If the session is not already authenticated, an authentication is
+        performed before sending the command - this can obviously fail if the
+        authentication details are not accepted, in which case an `OCIError`
+        exception is raised.
+
+        The response to the sent command is received and decoded.  The
+        received command object (or exception) is returned.
 
         Arguments:
             command: A single word name of a `OCIRequest()`

docs/usage.md

@@ -1,5 +1,24 @@
 # Usage
 
+## Summary
+
+Initially set up an API object to talk to the Broadworks server:-
+
+```python
+    from broadworks_ocip import BroadworksAPI
+
+    # configure the API, connect and authenticate to the server
+    api = BroadworksAPI(
+        host=args.host, port=args.port, username=args.username, password=args.password,
+    )
+```
+
+The API object is used to construct commands to Broadworks.  The details of
+the API methods and attributes are detailed in the
+[`BroadworksAPI` Documentation](api/api), but the main method used is the
+`command()` method.  This
+
+
 ## Simple Usage
 
 To use Broadworks OCI-P Interface in a project:-
@@ -28,7 +47,7 @@ To use Broadworks OCI-P Interface in a project:-
 ## More Complex Usage
 
 Some commands are more complex and made up of additional type components.
-This could lead to commands such as this::
+This could lead to commands such as this:-
 
 ```python
     result = api.command(