Add convenience for error handling and/or update Examples doc

[feltech]

#98 redesigns ManagerInterface methods to be batch-first, where exceptions are no longer raised but are instead returned as an element in the batch result. As discussed in https://github.com/TheFoundryVisionmongers/OpenAssetIO/pull/98#discussion_r756965041, this means the Examples page in the docs can no longer rely on the implicit error handling given by a potential exception.

We should update the Examples page to explicitly deal with errors and possibly add a mechanism to raise exceptions that are bundled in the result. E.g. a throwExceptions(...) adapter, or throwOnError=True method parameters.

[feltech]

A quick mock-up of two throwOnError possible implementations in C++, i.e. template parameter vs. out parameter, in Compiler Explorer such that the calls look like

void hostProcess()
{
    Strings urls;
    StringOrErrors urlOrErrors;

    // Using template parameter

    urlOrErrors = example1::resolveEntityReference<false>({"asset://ref"});
    try 
    {
        urls = example1::resolveEntityReference<true>({"asset://ref"});
    }
    catch (const EntityResolutionError& err)
    {
        // Boom!
    }

    // Using out parameter.

    example2::resolveEntityReference({"asset://ref"}, urlOrErrors);
    try
    {
        example2::resolveEntityReference({"asset://ref"}, urls);
    } 
    catch (const EntityResolutionError& err)
    {
        // Boom!
    }
}

Another option, which is essentially the same as the template parameter option, is just to have two separate methods, e.g. resolveEntityReferenceOrError vs. resolveEntityReferenceThrowOnError.

[feltech]

Thinking more about batch vs. singular methods: I think we should add a default singular version of all methods to ManagerInterface alongside the batch versions.

The default implementation will delegate to the batch version (and probably throw exceptions rather than return them).

We had already considered such singular wrappers, but as convenience methods in Manager, rather than ManagerInterface

However, by adding the convenience to ManagerInterface the manager plugin can opt to override the default implementation to optimise out the need to allocate then almost immediately deallocate single-element lists.

[foundrytom]

nb: we don't have returned results any more, and the callback approach highlights even more that a) we need to update the docs, and b) need some helpers for common scenarios where a single ref is being queried, as part of an exception-driven stack.

[foundrytom]

This highlights how painful working with a single entity ref can be in Python. This would be greatly simplified if they behaved like dicts of dicts, and we had an exception based wrapper for singular resolves.

[foundrytom]

Completed and tracked under #848