Improvements to Doxygen documentation.

kmhofmann · Jan 19, 2019 · efa18a3 · efa18a3
1 parent 348680f
commit efa18a3
Show file tree

Hide file tree

Showing 22 changed files with 82 additions and 75 deletions.
diff --git a/Doxyfile b/Doxyfile
@@ -119,7 +119,7 @@ RECURSIVE              = YES
 EXCLUDE                =
 EXCLUDE_SYMLINKS       = NO
 EXCLUDE_PATTERNS       =
-EXCLUDE_SYMBOLS        = impl
+EXCLUDE_SYMBOLS        = impl SELENE_*
 
 # The EXAMPLE_PATH tag can be used to specify one or more files or directories
 # that contain example code fragments that are included (see the \include
@@ -231,7 +231,7 @@ GENERATE_PERLMOD       = NO
 #---------------------------------------------------------------------------
 
 ENABLE_PREPROCESSING   = YES
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 EXPAND_ONLY_PREDEF     = NO
 SEARCH_INCLUDES        = YES
 INCLUDE_PATH           = "/home/michael/local/libtiff/include"
@@ -261,7 +261,7 @@ PERL_PATH              = /usr/bin/perl
 # Configuration options related to the dot tool
 #---------------------------------------------------------------------------
 
-CLASS_DIAGRAMS         = YES
+CLASS_DIAGRAMS         = NO
 HIDE_UNDOC_RELATIONS   = YES
 HAVE_DOT               = YES
 DOT_NUM_THREADS        = 0

diff --git a/selene/img/common/BoundingBox.hpp b/selene/img/common/BoundingBox.hpp
@@ -45,6 +45,11 @@ class BoundingBox
   PixelLength height_;
 };
 
+/// @}
+
+// ----------
+// Implementation:
+
 /** Default constructor. Constructs a bounding box of size (0, 0) top-left corner (0, 0).
  */
 constexpr BoundingBox::BoundingBox() noexcept
@@ -167,8 +172,6 @@ constexpr void BoundingBox::sanitize(PixelLength max_img_width, PixelLength max_
   height_ = std::min(height_, PixelLength{max_img_height - y0_});
 }
 
-/// @}
-
 }  // namespace sln
 
 #endif  // SELENE_IMG_COMMON_BOUNDING_BOX_HPP
diff --git a/selene/img/dynamic/UntypedLayout.hpp b/selene/img/dynamic/UntypedLayout.hpp
@@ -92,6 +92,8 @@ constexpr bool operator==(const UntypedImageSemantics& l, const UntypedImageSema
 
 constexpr bool operator!=(const UntypedImageSemantics& l, const UntypedImageSemantics& r);
 
+/// @}
+
 // ----------
 // Implementation:
 
@@ -180,8 +182,6 @@ constexpr bool operator!=(const UntypedImageSemantics& l, const UntypedImageSema
   return !(l == r);
 }
 
-/// @}
-
 }  // namespace sln
 
 #endif  // SELENE_IMG_DYNAMIC_UNTYPED_LAYOUT_HPP
diff --git a/selene/img/pixel/PixelTypeAliases.hpp b/selene/img/pixel/PixelTypeAliases.hpp
@@ -11,11 +11,24 @@
 
 namespace sln {
 
+// clang-format off
+
+#define SELENE_CREATE_PIXEL_TYPE_ALIAS(P, C) \
+    template <typename T> using Pixel ## P = Pixel<T, C, PixelFormat::P>; \
+    using Pixel ## P ## _8u  = Pixel<std::uint8_t,  C, PixelFormat::P>;   \
+    using Pixel ## P ## _8s  = Pixel<std::int8_t,   C, PixelFormat::P>;   \
+    using Pixel ## P ## _16u = Pixel<std::uint16_t, C, PixelFormat::P>;   \
+    using Pixel ## P ## _16s = Pixel<std::int16_t,  C, PixelFormat::P>;   \
+    using Pixel ## P ## _32u = Pixel<std::uint32_t, C, PixelFormat::P>;   \
+    using Pixel ## P ## _32s = Pixel<std::int32_t,  C, PixelFormat::P>;   \
+    using Pixel ## P ## _64u = Pixel<std::uint64_t, C, PixelFormat::P>;   \
+    using Pixel ## P ## _64s = Pixel<std::int64_t,  C, PixelFormat::P>;   \
+    using Pixel ## P ## _32f = Pixel<float32_t,     C, PixelFormat::P>;   \
+    using Pixel ## P ## _64f = Pixel<float64_t,     C, PixelFormat::P>;
+
 /// \addtogroup group-img-pixel-alias
 /// @{
 
-// clang-format off
-
 using Pixel_8u1 = Pixel<std::uint8_t, 1, PixelFormat::Unknown>;  ///< 8-bit unsigned 1-channel pixel.
 using Pixel_8u2 = Pixel<std::uint8_t, 2, PixelFormat::Unknown>;  ///< 8-bit unsigned 2-channel pixel.
 using Pixel_8u3 = Pixel<std::uint8_t, 3, PixelFormat::Unknown>;  ///< 8-bit unsigned 3-channel pixel.
@@ -66,18 +79,7 @@ using Pixel_64f2 = Pixel<float64_t, 2, PixelFormat::Unknown>;  ///< 64-bit float
 using Pixel_64f3 = Pixel<float64_t, 3, PixelFormat::Unknown>;  ///< 64-bit floating point 3-channel pixel.
 using Pixel_64f4 = Pixel<float64_t, 4, PixelFormat::Unknown>;  ///< 64-bit floating point 4-channel pixel.
 
-#define SELENE_CREATE_PIXEL_TYPE_ALIAS(P, C) \
-    template <typename T> using Pixel ## P = Pixel<T, C, PixelFormat::P>; \
-    using Pixel ## P ## _8u  = Pixel<std::uint8_t,  C, PixelFormat::P>;   \
-    using Pixel ## P ## _8s  = Pixel<std::int8_t,   C, PixelFormat::P>;   \
-    using Pixel ## P ## _16u = Pixel<std::uint16_t, C, PixelFormat::P>;   \
-    using Pixel ## P ## _16s = Pixel<std::int16_t,  C, PixelFormat::P>;   \
-    using Pixel ## P ## _32u = Pixel<std::uint32_t, C, PixelFormat::P>;   \
-    using Pixel ## P ## _32s = Pixel<std::int32_t,  C, PixelFormat::P>;   \
-    using Pixel ## P ## _64u = Pixel<std::uint64_t, C, PixelFormat::P>;   \
-    using Pixel ## P ## _64s = Pixel<std::int64_t,  C, PixelFormat::P>;   \
-    using Pixel ## P ## _32f = Pixel<float32_t,     C, PixelFormat::P>;   \
-    using Pixel ## P ## _64f = Pixel<float64_t,     C, PixelFormat::P>;
+
 
 SELENE_CREATE_PIXEL_TYPE_ALIAS(Y, 1)
 SELENE_CREATE_PIXEL_TYPE_ALIAS(YA, 2)

diff --git a/selene/img/typed/ImageTypeAliases.hpp b/selene/img/typed/ImageTypeAliases.hpp
@@ -12,11 +12,24 @@
 
 namespace sln {
 
+// clang-format off
+
+#define SELENE_CREATE_IMAGE_TYPE_ALIAS(P, C) \
+    template <typename T> using Image ## P = Image<Pixel<T, C, PixelFormat::P>>; \
+    using Image ## P ## _8u  = Image<Pixel<std::uint8_t,  C, PixelFormat::P>>;   \
+    using Image ## P ## _8s  = Image<Pixel<std::int8_t,   C, PixelFormat::P>>;   \
+    using Image ## P ## _16u = Image<Pixel<std::uint16_t, C, PixelFormat::P>>;   \
+    using Image ## P ## _16s = Image<Pixel<std::int16_t,  C, PixelFormat::P>>;   \
+    using Image ## P ## _32u = Image<Pixel<std::uint32_t, C, PixelFormat::P>>;   \
+    using Image ## P ## _32s = Image<Pixel<std::int32_t,  C, PixelFormat::P>>;   \
+    using Image ## P ## _64u = Image<Pixel<std::uint64_t, C, PixelFormat::P>>;   \
+    using Image ## P ## _64s = Image<Pixel<std::int64_t,  C, PixelFormat::P>>;   \
+    using Image ## P ## _32f = Image<Pixel<float32_t,     C, PixelFormat::P>>;   \
+    using Image ## P ## _64f = Image<Pixel<float64_t,     C, PixelFormat::P>>;
+
 /// \addtogroup group-img-typed-alias
 /// @{
 
-// clang-format off
-
 using Image_8u1 = Image<Pixel<std::uint8_t, 1>>;  ///< 8-bit unsigned 1-channel image.
 using Image_8u2 = Image<Pixel<std::uint8_t, 2>>;  ///< 8-bit unsigned 2-channel image.
 using Image_8u3 = Image<Pixel<std::uint8_t, 3>>;  ///< 8-bit unsigned 3-channel image.
@@ -67,19 +80,6 @@ using Image_64f2 = Image<Pixel<float64_t, 2>>;  ///< 64-bit floating point 2-cha
 using Image_64f3 = Image<Pixel<float64_t, 3>>;  ///< 64-bit floating point 3-channel image.
 using Image_64f4 = Image<Pixel<float64_t, 4>>;  ///< 64-bit floating point 4-channel image.
 
-#define SELENE_CREATE_IMAGE_TYPE_ALIAS(P, C) \
-    template <typename T> using Image ## P = Image<Pixel<T, C, PixelFormat::P>>; \
-    using Image ## P ## _8u  = Image<Pixel<std::uint8_t,  C, PixelFormat::P>>;   \
-    using Image ## P ## _8s  = Image<Pixel<std::int8_t,   C, PixelFormat::P>>;   \
-    using Image ## P ## _16u = Image<Pixel<std::uint16_t, C, PixelFormat::P>>;   \
-    using Image ## P ## _16s = Image<Pixel<std::int16_t,  C, PixelFormat::P>>;   \
-    using Image ## P ## _32u = Image<Pixel<std::uint32_t, C, PixelFormat::P>>;   \
-    using Image ## P ## _32s = Image<Pixel<std::int32_t,  C, PixelFormat::P>>;   \
-    using Image ## P ## _64u = Image<Pixel<std::uint64_t, C, PixelFormat::P>>;   \
-    using Image ## P ## _64s = Image<Pixel<std::int64_t,  C, PixelFormat::P>>;   \
-    using Image ## P ## _32f = Image<Pixel<float32_t,     C, PixelFormat::P>>;   \
-    using Image ## P ## _64f = Image<Pixel<float64_t,     C, PixelFormat::P>>;
-
 SELENE_CREATE_IMAGE_TYPE_ALIAS(Y, 1)
 SELENE_CREATE_IMAGE_TYPE_ALIAS(YA, 2)
 SELENE_CREATE_IMAGE_TYPE_ALIAS(RGB, 3)
@@ -94,12 +94,12 @@ SELENE_CREATE_IMAGE_TYPE_ALIAS(ABGR, 4)
 SELENE_CREATE_IMAGE_TYPE_ALIAS(CMYK, 4)
 SELENE_CREATE_IMAGE_TYPE_ALIAS(YCCK, 4)
 
+/// @}
+
 #undef SELENE_CREATE_IMAGE_TYPE_ALIAS
 
 // clang-format on
 
-/// @}
-
 }  // namespace sln
 
 #endif  // SELENE_IMG_TYPED_IMAGE_TYPE_ALIASES_HPP
diff --git a/selene/img/typed/ImageViewTypeAliases.hpp b/selene/img/typed/ImageViewTypeAliases.hpp
@@ -12,9 +12,6 @@
 
 namespace sln {
 
-/// \addtogroup group-img-typed-alias
-/// @{
-
 // clang-format off
 
 #define SELENE_CREATE_IMAGE_VIEW_TYPE_ALIAS(TMPL, MOD_PRE, C, MOD) \
@@ -29,6 +26,9 @@ namespace sln {
     TMPL using MOD_PRE ## ImageView_32f ## C = ImageView<Pixel<float32_t,     C>, MOD>; \
     TMPL using MOD_PRE ## ImageView_64f ## C = ImageView<Pixel<float64_t,     C>, MOD>; \
 
+/// \addtogroup group-img-typed-alias
+/// @{
+
 SELENE_CREATE_IMAGE_VIEW_TYPE_ALIAS(template <ImageModifiability modifiability>, , 1, modifiability)
 SELENE_CREATE_IMAGE_VIEW_TYPE_ALIAS(template <ImageModifiability modifiability>, , 2, modifiability)
 SELENE_CREATE_IMAGE_VIEW_TYPE_ALIAS(template <ImageModifiability modifiability>, , 3, modifiability)
@@ -44,6 +44,8 @@ SELENE_CREATE_IMAGE_VIEW_TYPE_ALIAS(, Constant, 2, ImageModifiability::Constant)
 SELENE_CREATE_IMAGE_VIEW_TYPE_ALIAS(, Constant, 3, ImageModifiability::Constant)
 SELENE_CREATE_IMAGE_VIEW_TYPE_ALIAS(, Constant, 4, ImageModifiability::Constant)
 
+/// @}
+
 #undef SELENE_CREATE_IMAGE_VIEW_TYPE_ALIAS
 
 #define SELENE_CREATE_IMAGE_VIEW_TYPE_ALIAS(P, C) \
@@ -70,6 +72,9 @@ SELENE_CREATE_IMAGE_VIEW_TYPE_ALIAS(, Constant, 4, ImageModifiability::Constant)
     using ConstantImageView ## P ## _32f = ImageView<Pixel<float32_t,     C, PixelFormat::P>, ImageModifiability::Constant>;   \
     using ConstantImageView ## P ## _64f = ImageView<Pixel<float64_t,     C, PixelFormat::P>, ImageModifiability::Constant>;   \
 
+/// \addtogroup group-img-typed-alias
+/// @{
+
 SELENE_CREATE_IMAGE_VIEW_TYPE_ALIAS(Y, 1)
 SELENE_CREATE_IMAGE_VIEW_TYPE_ALIAS(YA, 2)
 SELENE_CREATE_IMAGE_VIEW_TYPE_ALIAS(RGB, 3)
@@ -84,12 +89,12 @@ SELENE_CREATE_IMAGE_VIEW_TYPE_ALIAS(ABGR, 4)
 SELENE_CREATE_IMAGE_VIEW_TYPE_ALIAS(CMYK, 4)
 SELENE_CREATE_IMAGE_VIEW_TYPE_ALIAS(YCCK, 4)
 
+/// @}
+
 #undef SELENE_CREATE_IMAGE_VIEW_TYPE_ALIAS
 
 // clang-format on
 
-/// @}
-
 }  // namespace sln
 
 #endif  // SELENE_IMG_TYPED_IMAGE_VIEW_TYPE_ALIASES_HPP
diff --git a/selene/img/typed/TypedLayout.hpp b/selene/img/typed/TypedLayout.hpp
@@ -59,6 +59,8 @@ constexpr bool operator==(const TypedLayout& l, const TypedLayout& r);
 
 constexpr bool operator!=(const TypedLayout& l, const TypedLayout& r);
 
+/// @}
+
 // ----------
 // Implementation:
 
@@ -131,8 +133,6 @@ constexpr  bool operator!=(const TypedLayout& l, const TypedLayout& r)
   return !(l == r);
 }
 
-/// @}
-
 }  // namespace sln
 
 #endif  // SELENE_IMG_TYPED__TYPED_LAYOUT_HPP
diff --git a/selene/img_io/jpeg/Read.hpp b/selene/img_io/jpeg/Read.hpp
@@ -244,6 +244,8 @@ class JPEGReader
   void reset();
 };
 
+/// @}
+
 // ----------
 // Implementation:
 
@@ -521,8 +523,6 @@ void JPEGReader<SourceType>::reset()
   valid_header_read_ = false;
 }
 
-/// @}
-
 }  // namespace sln
 
 #endif  // defined(SELENE_WITH_LIBJPEG)

diff --git a/selene/img_io/jpeg/Write.hpp b/selene/img_io/jpeg/Write.hpp
@@ -144,6 +144,8 @@ bool write_jpeg(const DynImageOrView& dyn_img_or_view,
                 JPEGCompressionOptions options = JPEGCompressionOptions(),
                 MessageLog* messages = nullptr);
 
+/// @}
+
 // ----------
 // Implementation:
 
@@ -237,8 +239,6 @@ bool write_jpeg(const DynImageOrView& dyn_img_or_view,
   return !obj.error_state();
 }
 
-/// @}
-
 }  // namespace sln
 
 #endif  // defined(SELENE_WITH_LIBJPEG)

diff --git a/selene/img_io/png/Read.hpp b/selene/img_io/png/Read.hpp
@@ -272,6 +272,7 @@ class PNGReader
   void reset();
 };
 
+/// @}
 
 // ----------
 // Implementation:
@@ -570,8 +571,6 @@ void PNGReader<SourceType>::reset()
   valid_header_read_ = false;
 }
 
-/// @}
-
 }  // namespace sln
 
 #endif  // defined(SELENE_WITH_LIBPNG)

diff --git a/selene/img_io/png/Write.hpp b/selene/img_io/png/Write.hpp
@@ -146,6 +146,8 @@ bool write_png(const DynImageOrView& dyn_img_or_view,
                PNGCompressionOptions options = PNGCompressionOptions(),
                MessageLog* messages = nullptr);
 
+/// @}
+
 // ----------
 // Implementation:
 
@@ -232,8 +234,6 @@ bool write_png(const DynImageOrView& dyn_img_or_view,
   return !obj.error_state();
 }
 
-/// @}
-
 }  // namespace sln
 
 #endif  // defined(SELENE_WITH_LIBPNG)

diff --git a/selene/img_io/tiff/Read.hpp b/selene/img_io/tiff/Read.hpp
@@ -119,6 +119,8 @@ class TIFFReader
   MessageLog message_log_;
 };
 
+/// @}
+
 // ----------
 // Implementation:
 
@@ -350,8 +352,6 @@ MessageLog& TIFFReader<SourceType>::message_log()
   return message_log_;
 }
 
-/// @}
-
 }  // namespace sln
 
 #endif  // defined(SELENE_WITH_LIBTIFF)

diff --git a/selene/img_io/tiff/Write.hpp b/selene/img_io/tiff/Write.hpp
@@ -156,6 +156,8 @@ class TIFFWriter
   std::ptrdiff_t nr_images_written{0};
 };
 
+/// @}
+
 // ----------
 // Implementation:
 
@@ -261,8 +263,6 @@ MessageLog& TIFFWriter<SinkType>::message_log()
   return message_log_;
 }
 
-/// @}
-
 }  // namespace sln
 
 #endif  // defined(SELENE_WITH_LIBTIFF)

diff --git a/selene/img_ops/ChannelOperations.hpp b/selene/img_ops/ChannelOperations.hpp
@@ -24,6 +24,8 @@ void inject_channels(const ImgSrc& src, ImgDst& dst, std::size_t dst_start_chann
 template <sln::PixelFormat pixel_format = sln::PixelFormat::Unknown, typename... Imgs>
 auto stack_images(Imgs... imgs);
 
+/// @}
+
 // ----------
 // Implementation:
 
@@ -186,8 +188,6 @@ auto stack_images(Imgs... imgs)
   return img_dst;
 }
 
-/// @}
-
 }  // namespace sln
 
 #endif  // SELENE_IMG_OPS_CHANNEL_OPERATIONS_HPP

diff --git a/selene/img_ops/Clone.hpp b/selene/img_ops/Clone.hpp
@@ -29,6 +29,8 @@ Image<typename DerivedSrc::PixelType> clone(const ImageBase<DerivedSrc>& img_src
 template <typename DerivedSrc>
 Image<typename DerivedSrc::PixelType> clone(const ImageBase<DerivedSrc>& img_src, const BoundingBox& region_src);
 
+/// @}
+
 // ----------
 // Implementation:
 
@@ -150,8 +152,6 @@ Image<typename DerivedSrc::PixelType> clone(const ImageBase<DerivedSrc>& img_src
   return img_dst;
 }
 
-/// @}
-
 }  // namespace sln
 
 #endif  // SELENE_IMG_OPS_CLONE_HPP