Trade: document AnimationData usage.

This is the last non-obvious thing that needs to be documented in order
to make the API usable.

doc/snippets/MagnumTrade.cpp

@@ -27,8 +27,10 @@
 #include <Corrade/Utility/Directory.h>
 
 #include "Magnum/PixelFormat.h"
+#include "Magnum/Animation/Player.h"
 #include "Magnum/MeshTools/Transform.h"
 #include "Magnum/Trade/AbstractImporter.h"
+#include "Magnum/Trade/AnimationData.h"
 #include "Magnum/Trade/ImageData.h"
 #include "Magnum/Trade/MeshData2D.h"
 #include "Magnum/Trade/MeshData3D.h"
@@ -133,6 +135,29 @@ importer->setFileCallback([](const std::string& filename,
 /* [AbstractImporter-setFileCallback-template] */
 }
 
+{
+UnsignedInt id{};
+std::unique_ptr<Trade::AbstractImporter> importer;
+/* [AnimationData-usage] */
+
+Containers::Optional<Trade::AnimationData> data = importer->animation(id);
+
+Animation::Player<Float> player;
+Containers::Array<Vector3> positions; /* Translations for all objects */
+for(UnsignedInt i = 0; i != data->trackCount(); ++i) {
+    if(data->trackTarget(i) == Trade::AnimationTrackTarget::Translation3D) {
+        CORRADE_INTERNAL_ASSERT(data->trackType(i) ==
+            Trade::AnimationTrackType::Vector3);
+        player.add(data->track<Vector3>(i), positions[data->trackTargetId(i)]);
+    }
+
+    // similarly for rotation / scaling ...
+}
+
+Containers::Array<char> animationData = data->release(); /* Take ownership */
+/* [AnimationData-usage] */
+}
+
 {
 /* [ImageData-construction] */
 Containers::Array<char> data;

src/Magnum/Trade/AnimationData.h

@@ -201,7 +201,26 @@ class AnimationTrackData {
 /**
 @brief Animation clip data
 
-@see @ref AbstractImporter::animation()
+Provides access to animation data and track properties of given clip. The
+instance is commonly returned from @ref AbstractImporter::animation() and a
+typical usage is feeding all the tracks directly to @ref Animation::Player.
+For every track, you need to query its concrete type and then feed the
+resulting @ref Animation::TrackView of correct type to
+@ref Animation::Player::add(), for example.
+
+Note that this class owns the animation track data and the tracks are only
+views on it. In order to be able to destroy the @ref AnimationData instance and
+keep using the animations later, you need to take ownership of the data using
+@ref release().
+
+In the following snippet all animated positions are stored in an array. The
+array is then updated during calls to @ref Animation::Player::advance().
+
+@snippet MagnumTrade.cpp AnimationData-usage
+
+It's also possible to directly update object transformations using callbacks,
+among other things. See documentation of the @ref Animation::Player class for
+more information.
 @experimental
 */
 class MAGNUM_TRADE_EXPORT AnimationData {