diff --git a/lib/pact_broker/api/decorators/version_decorator.rb b/lib/pact_broker/api/decorators/version_decorator.rb
index 7026fad7b..875d95884 100644
--- a/lib/pact_broker/api/decorators/version_decorator.rb
+++ b/lib/pact_broker/api/decorators/version_decorator.rb
@@ -21,6 +21,7 @@ class VersionDecorator < BaseDecorator
           {
             title: "Version",
             name: represented.number,
+            # This decorator is used for multiple Version resources, so dynamically fetch the current resource URL
             href: options.fetch(:resource_url)
           }
         end
diff --git a/lib/pact_broker/api/decorators/versions_decorator.rb b/lib/pact_broker/api/decorators/versions_decorator.rb
index d65341c71..3cb016e61 100644
--- a/lib/pact_broker/api/decorators/versions_decorator.rb
+++ b/lib/pact_broker/api/decorators/versions_decorator.rb
@@ -6,11 +6,9 @@ module PactBroker
   module Api
     module Decorators
       class VersionsDecorator < BaseDecorator
-
         class VersionInCollectionDecorator < PactBroker::Api::Decorators::VersionDecorator
-
-          # VersionDecorator has a dynamic self URL, depending which path the Version resource is mounted at
-          # Hardcode the URL of the Versions in the collection to the URL with the number.
+          # VersionDecorator has a dynamic self URL, depending which path the Version resource is mounted at.
+          # Hardcode the URL of the embedded Versions in this collection to use the canonical URL with the version number.
           link :self do | user_options |
             {
               title: "Version",