[Docs] Add a little more info about the implementation

Signed-off-by: Tom Cowland <[email protected]>
OpenAssetIO · Aug 16, 2023 · 5534abf · 5534abf
1 parent 01fe887
commit 5534abf
Showing 1 changed file with 52 additions and 20 deletions.
diff --git a/src/resolver.cpp b/src/resolver.cpp
@@ -38,7 +38,13 @@ TF_DEBUG_CODES(OPENASSETIO_RESOLVER)
 PXR_NAMESPACE_CLOSE_SCOPE
 
 namespace {
-/// Converter logger from OpenAssetIO log framing to USD log outputs.
+
+/*
+ * OpenAssetIO LoggerInterface implementation
+ *
+ * Converter logger from OpenAssetIO log framing to USD log outputs.
+ */
+
 class UsdOpenAssetIOResolverLogger : public openassetio::log::LoggerInterface {
  public:
   void log(Severity severity, const openassetio::Str &message) override {
@@ -51,8 +57,6 @@ class UsdOpenAssetIOResolverLogger : public openassetio::log::LoggerInterface {
         TF_DEBUG(OPENASSETIO_RESOLVER).Msg(message + "\n");
         break;
       case Severity::kError:
-        // TODO(EM) : Review to see which error types are most appropriate,
-        //  are all errors (not criticals) non fatal?
         TF_ERROR(TfDiagnosticType::TF_DIAGNOSTIC_NONFATAL_ERROR_TYPE, message);
         break;
       case Severity::kInfo:
@@ -66,6 +70,13 @@ class UsdOpenAssetIOResolverLogger : public openassetio::log::LoggerInterface {
   }
 };
 
+/**
+ * OpenAssetIO HostInterface implementation
+ *
+ * This identifies the Ar2 plugin uniquely should the manager plugin
+ * wish to adapt its behaviour.
+ */
+
 class UsdOpenAssetIOHostInterface : public openassetio::hostApi::HostInterface {
  public:
   [[nodiscard]] openassetio::Identifier identifier() const override {
@@ -160,9 +171,11 @@ auto catchAndLogExceptions(Fn &&fn, const openassetio::log::LoggerInterfacePtr &
 }
 }  // namespace
 
-
 // ------------------------------------------------------------
-/* Ar Resolver Implementation */
+
+/*
+ * Ar Resolver Implementation
+ */
 
 UsdOpenAssetIOResolver::UsdOpenAssetIOResolver() {
   // Note: it is safe to throw exceptions from the constructor. USD will
@@ -186,13 +199,16 @@ UsdOpenAssetIOResolver::UsdOpenAssetIOResolver() {
         openassetio::hostApi::ManagerFactory::kDefaultManagerConfigEnvVarName};
   }
 
-  // TODO(DF): Set appropriate locale.
   readContext_ = openassetio::Context::make(openassetio::Context::Access::kRead,
                                             openassetio::Context::Retention::kTransient);
 }
 
 UsdOpenAssetIOResolver::~UsdOpenAssetIOResolver() {}
 
+/*
+ * Read
+ */
+
 std::string UsdOpenAssetIOResolver::_CreateIdentifier(
     const std::string &assetPath, const ArResolvedPath &anchorAssetPath) const {
   return catchAndLogExceptions(
@@ -206,7 +222,7 @@ std::string UsdOpenAssetIOResolver::_CreateIdentifier(
           // resolve to an absolute path, making the anchorAssetPath redundant
           // (for now).
           // TODO(DF): Allow the manager to provide an identifier representing
-          //  an "anchored" entity reference.
+          //  an "anchored" entity reference via getWithRelationship.
           identifier = assetPath;
         } else {
           identifier = ArDefaultResolver::_CreateIdentifier(assetPath, anchorAssetPath);
@@ -217,17 +233,6 @@ std::string UsdOpenAssetIOResolver::_CreateIdentifier(
       logger_, TF_FUNC_NAME());
 }
 
-std::string UsdOpenAssetIOResolver::_CreateIdentifierForNewAsset(
-    const std::string &assetPath, const ArResolvedPath &anchorAssetPath) const {
-  if (manager_->isEntityReferenceString(assetPath)) {
-    std::string message = "Writes to OpenAssetIO entity references are not currently supported ";
-    message += assetPath;
-    logger_->critical(message);
-    return "";
-  }
-  return ArDefaultResolver::_CreateIdentifierForNewAsset(assetPath, anchorAssetPath);
-}
-
 ArResolvedPath UsdOpenAssetIOResolver::_Resolve(const std::string &assetPath) const {
   return catchAndLogExceptions(
       [&] {
@@ -239,6 +244,26 @@ ArResolvedPath UsdOpenAssetIOResolver::_Resolve(const std::string &assetPath) co
       logger_, TF_FUNC_NAME());
 }
 
+/*
+ * Write
+ *
+ * We don't currently support writes to OpenAssetIO entity references.
+ * In order to call register when the ArAsset is closed, we'll need
+ * not resolve in _ResolveForNewAsset, and pass the entity reference
+ * through.
+ */
+
+std::string UsdOpenAssetIOResolver::_CreateIdentifierForNewAsset(
+    const std::string &assetPath, const ArResolvedPath &anchorAssetPath) const {
+  if (manager_->isEntityReferenceString(assetPath)) {
+    std::string message = "Writes to OpenAssetIO entity references are not currently supported ";
+    message += assetPath;
+    logger_->critical(message);
+    return "";
+  }
+  return ArDefaultResolver::_CreateIdentifierForNewAsset(assetPath, anchorAssetPath);
+}
+
 ArResolvedPath UsdOpenAssetIOResolver::_ResolveForNewAsset(const std::string &assetPath) const {
   if (manager_->isEntityReferenceString(assetPath)) {
     std::string message = "Writes to OpenAssetIO entity references are not currently supported ";
@@ -251,6 +276,15 @@ ArResolvedPath UsdOpenAssetIOResolver::_ResolveForNewAsset(const std::string &as
 
 /*
  * Pass-through asset operations
+ *
+ * These methods are simply relayed to the ArDefaultResolver. There may
+ * be interest in fetching data for some of these from the manager, but
+ * we don't have a real use case just yet. Doing so increases complexity
+ * as we'd need to return both the resolved path _and_ the original
+ * entity reference from _Resolve, so we could make queries in these
+ * methods. We'll need this for publishing operations, but avoiding that
+ * overhead for the more common (and hot) read case is critical.
+ *
  */
 std::string UsdOpenAssetIOResolver::_GetExtension(const std::string &assetPath) const {
   return ArDefaultResolver::_GetExtension(assetPath);
@@ -271,13 +305,11 @@ std::shared_ptr<ArAsset> UsdOpenAssetIOResolver::_OpenAsset(
   return ArDefaultResolver::_OpenAsset(resolvedPath);
 }
 
-// TODO(DF): Implement for publishing workflow.
 bool UsdOpenAssetIOResolver::_CanWriteAssetToPath(const ArResolvedPath &resolvedPath,
                                                   std::string *whyNot) const {
   return ArDefaultResolver::_CanWriteAssetToPath(resolvedPath, whyNot);
 }
 
-// TODO(DF): Implement for publishing workflow.
 std::shared_ptr<ArWritableAsset> UsdOpenAssetIOResolver::_OpenAssetForWrite(
     const ArResolvedPath &resolvedPath, WriteMode writeMode) const {
   return ArDefaultResolver::_OpenAssetForWrite(resolvedPath, writeMode);