Various minor documentation cleanups/improvements

Author: sgretscher

ChangeLog.txt

@@ -20,6 +20,7 @@ ARA SDK 2.0 draft 15 (aka 1.9.15) (2021/??/??)
   Plug-Ins vendors that have relied on the previous behavior must update their code accordingly -
   running the test host will trigger all relevant code paths to validate the changed code.
 - refactored StoreObjectsFilter c'tor to make it usable without a DocumentController*
+- various minor documentation cleanups/improvements
 
 ARA SDK 2.0 draft 14 (aka 1.9.14) (2021/02/26)
 - applied Apache License 2.0

Debug/ARAContentValidator.h

@@ -113,9 +113,8 @@ struct ContentReaderValidatorImplementation<kARAContentTypeStaticTuning>
 template <>
 struct ContentReaderValidatorImplementation<kARAContentTypeKeySignatures>
 {
-//! \todo this can currently fail in Studio One
-//  static inline void validateEventCount (ARAInt32 eventCount) { ARA_VALIDATE_API_CONDITION (eventCount > 0); }
-    static inline void validateEventCount (ARAInt32 eventCount) { ARA_VALIDATE_API_CONDITION (eventCount >= 0); }
+    // this may fail in older versions of Studio One if no key has been set for the song - fixed in version 5.2.1
+    static inline void validateEventCount (ARAInt32 eventCount) { ARA_VALIDATE_API_CONDITION (eventCount > 0); }
 
     static inline void validateEvent (const ARAContentKeySignature* /*event*/) {}
 

Debug/ARADebug.h

@@ -59,7 +59,7 @@ extern "C"
         kARADebugLevelAssert = 2    // output indicates programming error
     } ARADebugLevel;
 
-    // primitve macro for all debug output
+    // primitive macro for all debug output
     // can be overridden by SDK clients to use their own custom logging system
     // typically not called directly - instead ARA_LOG, ARA_WARN or asserts are used
     #if !defined(ARA_DEBUG_MESSAGE)

Dispatch/ARAContentReader.h

@@ -56,7 +56,7 @@ struct ContentTypeMapper;
 
 /*******************************************************************************/
 // ContentReaderFunctionMapper
-// Map to allow templated content reader code to pick the proper non-polymporhic ARA interface calls.
+// Map to allow templated content reader code to pick the proper non-polymorphic ARA interface calls.
 /*******************************************************************************/
 
 template <typename ControllerType, typename ModelObjectRefType> struct ContentReaderFunctionMapper;

Dispatch/ARAHostDispatch.cpp

@@ -450,24 +450,24 @@ ARARegionSequenceRef DocumentController::createRegionSequence (ARARegionSequence
     return getInterface ()->createRegionSequence (getRef (), hostRef, properties);
 }
 
-void DocumentController::updateRegionSequenceProperties (ARARegionSequenceRef regionSequencRef, const ARARegionSequenceProperties* properties) noexcept
+void DocumentController::updateRegionSequenceProperties (ARARegionSequenceRef regionSequenceRef, const ARARegionSequenceProperties* properties) noexcept
 {
 #if ARA_SUPPORT_VERSION_1
     if (!getInterface ().implements<ARA_STRUCT_MEMBER (ARADocumentControllerInterface, destroyRegionSequence)> ())
         return;
 #endif
 
-    return getInterface ()->updateRegionSequenceProperties (getRef (), regionSequencRef, properties);
+    return getInterface ()->updateRegionSequenceProperties (getRef (), regionSequenceRef, properties);
 }
 
-void DocumentController::destroyRegionSequence (ARARegionSequenceRef regionSequencRef) noexcept
+void DocumentController::destroyRegionSequence (ARARegionSequenceRef regionSequenceRef) noexcept
 {
 #if ARA_SUPPORT_VERSION_1
     if (!getInterface ().implements<ARA_STRUCT_MEMBER (ARADocumentControllerInterface, destroyRegionSequence)> ())
         return;
 #endif
 
-    return getInterface ()->destroyRegionSequence (getRef (), regionSequencRef);
+    return getInterface ()->destroyRegionSequence (getRef (), regionSequenceRef);
 }
 
 ARAAudioSourceRef DocumentController::createAudioSource (ARAAudioSourceHostRef hostRef, const ARAAudioSourceProperties* properties) noexcept
@@ -784,14 +784,14 @@ void EditorRenderer::removePlaybackRegion (ARAPlaybackRegionRef playbackRegionRe
     getInterface ()->removePlaybackRegion (getRef (), playbackRegionRef);
 }
 
-void EditorRenderer::addRegionSequence (ARARegionSequenceRef regionSequencRef) noexcept
+void EditorRenderer::addRegionSequence (ARARegionSequenceRef regionSequenceRef) noexcept
 {
-    getInterface ()->addRegionSequence (getRef (), regionSequencRef);
+    getInterface ()->addRegionSequence (getRef (), regionSequenceRef);
 }
 
-void EditorRenderer::removeRegionSequence (ARARegionSequenceRef regionSequencRef) noexcept
+void EditorRenderer::removeRegionSequence (ARARegionSequenceRef regionSequenceRef) noexcept
 {
-    getInterface ()->removeRegionSequence (getRef (), regionSequencRef);
+    getInterface ()->removeRegionSequence (getRef (), regionSequenceRef);
 }
 
 //************************************************************************************************

Dispatch/ARAHostDispatch.h

@@ -344,9 +344,9 @@ class DocumentController : public InterfaceInstance<ARADocumentControllerRef, AR
     //! \copydoc ARADocumentControllerInterface::createRegionSequence
     ARARegionSequenceRef createRegionSequence (ARARegionSequenceHostRef hostRef, const ARARegionSequenceProperties* properties) noexcept;
     //! \copydoc ARADocumentControllerInterface::updateRegionSequenceProperties
-    void updateRegionSequenceProperties (ARARegionSequenceRef regionSequencRef, const ARARegionSequenceProperties* properties) noexcept;
+    void updateRegionSequenceProperties (ARARegionSequenceRef regionSequenceRef, const ARARegionSequenceProperties* properties) noexcept;
     //! \copydoc ARADocumentControllerInterface::destroyRegionSequence
-    void destroyRegionSequence (ARARegionSequenceRef regionSequencRef) noexcept;
+    void destroyRegionSequence (ARARegionSequenceRef regionSequenceRef) noexcept;
 //@}
 
 //! @name Audio Source Management
@@ -526,8 +526,8 @@ class EditorRenderer : public InterfaceInstance<ARAEditorRendererRef, ARAEditorR
 //@{
     void addPlaybackRegion (ARAPlaybackRegionRef playbackRegionRef) noexcept;
     void removePlaybackRegion (ARAPlaybackRegionRef playbackRegionRef) noexcept;
-    void addRegionSequence (ARARegionSequenceRef regionSequencRef) noexcept;
-    void removeRegionSequence (ARARegionSequenceRef regionSequencRef) noexcept;
+    void addRegionSequence (ARARegionSequenceRef regionSequenceRef) noexcept;
+    void removeRegionSequence (ARARegionSequenceRef regionSequenceRef) noexcept;
 //@}
 };
 

Dispatch/ARAPlugInDispatch.cpp

@@ -615,7 +615,7 @@ void HostArchivingController::notifyDocumentUnarchivingProgress (float value) no
 
 ARAPersistentID HostArchivingController::getDocumentArchiveID (ARAArchiveReaderHostRef archiveReaderHostRef) noexcept
 {
-    // getDocumentArchiveID was added in the ARA 2.0 final, so check its presence here to support older hosts
+    // getDocumentArchiveID() was added in the ARA 2.0 final release, so check its presence here to support older hosts
     if (getInterface ().implements<ARA_STRUCT_MEMBER (ARAArchivingControllerInterface, getDocumentArchiveID)> ())
         return getInterface ()->getDocumentArchiveID (getRef (), archiveReaderHostRef);
     return nullptr;

Dispatch/ARAPlugInDispatch.h

@@ -75,7 +75,7 @@ namespace PlugIn {
 #endif
 
 /*******************************************************************************/
-/** Tag objects maintained by the host to prevent accidently copying/moving them. */
+/** Tag objects maintained by the host to prevent accidentally copying/moving them. */
 /*******************************************************************************/
 
 #if !defined (ARA_HOST_MANAGED_OBJECT)

PlugIn/ARAPlug.cpp

@@ -157,7 +157,7 @@ void logToStream (const PlaybackRegion* playbackRegion, std::ostringstream& oss,
     if (detailed)
     {
         oss << ", modification:" << playbackRegion->getStartInAudioModificationTime () << " to " << playbackRegion->getEndInAudioModificationTime ()
-            << ", timestretching:" << (playbackRegion->isTimestretchEnabled () ? (playbackRegion->isTimeStretchReflectingTempo () ? "musical" : "linear") : "off)")
+            << ", time-stretching:" << (playbackRegion->isTimestretchEnabled () ? (playbackRegion->isTimeStretchReflectingTempo () ? "musical" : "linear") : "off)")
             << ", content based fades:" << (playbackRegion->hasContentBasedFadeAtHead () ? (playbackRegion->hasContentBasedFadeAtTail () ? "both" : "head only") : (playbackRegion->hasContentBasedFadeAtTail () ? "tail only" : "none"))
             << ", regionSequence:" << playbackRegion->getRegionSequence ()->getName ()
             << ", color:"  << playbackRegion->getColor ();
@@ -596,13 +596,12 @@ void PlaybackRegion::updateProperties (PropertiesPtr<ARAPlaybackRegionProperties
     _durationInPlaybackTime = properties->durationInPlaybackTime;
 
 #if ARA_VALIDATE_API_CALLS
-//! \todo these currently fail in Studio One: they enable the time stretching flag even if not supported (but don't stretch),
-//!       and in some configurations also send slightly different time ranges even though not stretching.
-//  const auto supportedTransformationFlags = DocumentController::getARAFactory ()->supportedPlaybackTransformationFlags;
-//  ARA_VALIDATE_API_ARGUMENT (properties, (properties->transformationFlags & ~supportedTransformationFlags) == 0);
-//  if (((properties->transformationFlags & kARAPlaybackTransformationTimestretch) == 0) ||
-//      ((supportedTransformationFlags & kARAPlaybackTransformationTimestretch) == 0))
-//      ARA_VALIDATE_API_ARGUMENT (properties, properties->durationInModificationTime == properties->durationInPlaybackTime);
+    const auto supportedTransformationFlags { getDocumentController ()->getFactory ()->supportedPlaybackTransformationFlags };
+    // this may fail in older versions of Studio One which always set the flag (despite never actually stretching if not supported) - fixed in version 5.2.1
+    ARA_VALIDATE_API_ARGUMENT (properties, (properties->transformationFlags & ~supportedTransformationFlags) == 0);
+    if (((properties->transformationFlags & kARAPlaybackTransformationTimestretch) == 0) ||
+        ((supportedTransformationFlags & kARAPlaybackTransformationTimestretch) == 0))
+        ARA_VALIDATE_API_ARGUMENT (properties, properties->durationInModificationTime == properties->durationInPlaybackTime);
 #endif
 
     _timestretchEnabled = ((properties->transformationFlags & kARAPlaybackTransformationTimestretch) != 0);
@@ -2695,7 +2694,7 @@ void PlugInEntry::initializeARAWithConfiguration (const ARAInterfaceConfiguratio
 #if ARA_VALIDATE_API_CALLS
     ++_assertInitCount;
 #if defined (NDEBUG)
-    // when not debugging from our side, use host asserts if possible
+    // when not debugging from our side, use host asserts (if provided)
     ARASetExternalAssertReference (ptr->assertFunctionAddress);
 #else
     // when debugging from our side, switch host to our asserts

PlugIn/ARAPlug.h

@@ -519,7 +519,7 @@ class AudioModification
     //! provide a matching c'tor if subclassing AudioModification.
     //! \p optionalModificationToClone will be nullptr when creating new modifications with
     //! default state from scratch, or will point to a modification (referencing the same
-    //! \p audioSource) from which the internal state should be cloned into the new modifiction.
+    //! \p audioSource) from which the internal state should be cloned into the new modification.
     explicit AudioModification (AudioSource* audioSource, ARAAudioModificationHostRef hostRef, const AudioModification* optionalModificationToClone) noexcept;
 //@}
 
@@ -1195,10 +1195,15 @@ class DocumentController : public DocumentControllerInterface,
 
 //! @name Host Interface Access
 //@{
+    //! Returns the audio access controller that the host has provided for this document controller.
     HostAudioAccessController* getHostAudioAccessController () noexcept { return &_hostAudioAccessController; }
+    //! Returns the archiving controller that the host has provided for this document controller.
     HostArchivingController* getHostArchivingController () noexcept { return &_hostArchivingController; }
+    //! Returns the optional content access controller that the host has provided for this document controller.
     HostContentAccessController* getHostContentAccessController () noexcept { return (_hostContentAccessController.isProvided ()) ? &_hostContentAccessController : nullptr; }
+    //! Returns the optional model update controller that the host has provided for this document controller.
     HostModelUpdateController* getHostModelUpdateController () noexcept { return (_hostModelUpdateController.isProvided ()) ? &_hostModelUpdateController : nullptr; }
+    //! Returns the optional playback controller that the host has provided for this document controller.
     HostPlaybackController* getHostPlaybackController () noexcept { return (_hostPlaybackController.isProvided ()) ? &_hostPlaybackController : nullptr; }
 //@}
 
@@ -1277,13 +1282,15 @@ class DocumentController : public DocumentControllerInterface,
     friend class PlugInEntry;
 
     // Creation Helper
-    // Only to be called by ARAFactory::createDocumentControllerWithDocument () implementations.
+    // Only to be called by the ARAFactory::createDocumentControllerWithDocument () implementations
+    // provided via PlugInEntry.
     // Must be called directly after construction of the DocumentController
     // (cannot be called from constructor because it calls virtual functions).
     void initializeDocument (const ARADocumentProperties* properties) noexcept;
 
     // Creation Helper
-    // Only to be called by ARAFactory::createDocumentControllerWithDocument () implementations.
+    // Only to be called by the ARAFactory::createDocumentControllerWithDocument () implementations
+    // provided via PlugInEntry.
     const ARADocumentControllerInstance* getInstance () const noexcept { return &_instance; }
 #endif
 
@@ -1698,14 +1705,14 @@ class EditorView : public EditorViewInterface
 
 /*******************************************************************************/
 //! Utility class that wraps an ARAPlugInExtensionInstance.
-//! Each Companion API plug-in instance owns one PlugInExtension (or custom subclass thereof).
+//! Each companion API plug-in instance owns one PlugInExtension (or custom subclass thereof).
 class PlugInExtension
 {
 public:
     PlugInExtension () noexcept = default;
     virtual ~PlugInExtension () noexcept;
 
-    //! Establish the binding to ARA when requested through the Companion API,
+    //! Establish the binding to ARA when requested through the companion API,
     //! switching the plug-in from regular processing to ARA mode.
     const ARAPlugInExtensionInstance* bindToARA (ARADocumentControllerRef documentControllerRef, ARAPlugInInstanceRoleFlags knownRoles, ARAPlugInInstanceRoleFlags assignedRoles) noexcept;