From 84dcd52625172f15df61a0e4f6c53f2b216edd18 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Mon, 5 Apr 2021 17:29:57 +0200
Subject: [PATCH] DebugTools: doc++

---
 doc/snippets/debugtools-compareimage.cpp | 17 ++++++++++++-----
 src/Magnum/DebugTools/CompareImage.h     | 18 +++++++++++++++---
 2 files changed, 27 insertions(+), 8 deletions(-)

diff --git a/doc/snippets/debugtools-compareimage.cpp b/doc/snippets/debugtools-compareimage.cpp
index 2650aa18f..8dd0df16b 100644
--- a/doc/snippets/debugtools-compareimage.cpp
+++ b/doc/snippets/debugtools-compareimage.cpp
@@ -38,6 +38,8 @@
 
 using namespace Magnum;
 
+#define DOXYGEN_IGNORE(...) __VA_ARGS__
+
 namespace {
 
 Image2D doProcessing() {
@@ -68,17 +70,22 @@ struct ProcessingTest: TestSuite::Tester {
 
 ProcessingTest::ProcessingTest() {
     addTests({&ProcessingTest::process});
+
+    if(false) {
+/* [basic] */
+Image2D actual{DOXYGEN_IGNORE(doProcessing())}, expected{DOXYGEN_IGNORE(loadExpectedImage())};
+CORRADE_COMPARE_AS(actual, expected, DebugTools::CompareImage);
+/* [basic] */
+    }
 }
 
-/** [0] */
 void ProcessingTest::process() {
     Image2D actual = doProcessing();
     Image2D expected = loadExpectedImage();
-
-    CORRADE_COMPARE_WITH(actual, expected,
-        (DebugTools::CompareImage{170.0f, 96.0f}));
+/* [delta] */
+CORRADE_COMPARE_WITH(actual, expected, (DebugTools::CompareImage{170.0f, 96.0f}));
+/* [delta] */
 }
-/** [0] */
 
 CORRADE_TEST_MAIN(ProcessingTest)
 
diff --git a/src/Magnum/DebugTools/CompareImage.h b/src/Magnum/DebugTools/CompareImage.h
index 690402944..489c19fa7 100644
--- a/src/Magnum/DebugTools/CompareImage.h
+++ b/src/Magnum/DebugTools/CompareImage.h
@@ -200,15 +200,27 @@ template<class T, class U> struct ComparatorTraits<Magnum::DebugTools::CompareIm
 namespace Magnum { namespace DebugTools {
 
 /**
-@brief Image comparator
+@brief Image comparator for @ref Corrade::TestSuite
 
-To be used with @ref Corrade::TestSuite. Basic use is really simple:
+The simplest way to use the comparator is by passing it to
+@ref CORRADE_COMPARE_AS() along with an actual and expected image, as shown
+below. That will compare image sizes, pixel formats and pixel data for equality
+taking into account pixel storage parameters of each image, without requiring
+you to manually go through all relevant properties and looping over pixel data:
 
-@snippet debugtools-compareimage.cpp 0
+@snippet debugtools-compareimage.cpp basic
 
 @note For comparing image files, there are also @ref CompareImageFile,
     @ref CompareImageToFile and @ref CompareFileToImage variants.
 
+Where the comparator actually shines, however, is comparing with some delta ---
+since images produced by real-world hardware, algorithms and lossy compression
+schemes are rarely exactly bit-equal. Using @ref CORRADE_COMPARE_WITH() instead
+to be able to pass parameters to the constructor, it takes a max delta for a
+single pixel and mean delta averaged over all pixels:
+
+@snippet debugtools-compareimage.cpp delta
+
 Based on actual images used, in case of comparison failure the comparator can
 give for example the following output: