diff --git a/AGENTS.md b/AGENTS.md
index a6762bc23..055c6e556 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -283,6 +283,9 @@ Dispatch `release.yml` against main, publish the draft that appears —
   Detailed rationale belongs in the per-module `AGENTS.md`.
 - **Doc-comment markers**: `///` for functions/classes/structs/enums; trailing
   `///<` for the short note on the same line (enumerator/member). Keep terse.
+  **`@brief` only where there is a detail paragraph under it** — a lone
+  `@brief` marks nothing off from anything, so the tag is noise. Write the
+  description plainly; add `@brief` at the moment a second paragraph arrives.
 - **Pull requests**: put the `🤖 Generated with [Claude Code](https://claude.com/claude-code)`
   line **at the top** of the PR body. If the change is one a consumer would
   notice, add its `CHANGELOG.md` entry in the same PR — see *Releasing*.
diff --git a/src/odr/archive.hpp b/src/odr/archive.hpp
index 7d3ae06ec..4ec3de16b 100644
--- a/src/odr/archive.hpp
+++ b/src/odr/archive.hpp
@@ -10,7 +10,7 @@ class Archive;
 namespace odr {
 class Filesystem;
 
-/// @brief Represents an archive file.
+/// Represents an archive file.
 class Archive {
 public:
   explicit Archive(std::shared_ptr<internal::abstract::Archive>);
diff --git a/src/odr/document.hpp b/src/odr/document.hpp
index 21fb40c55..6221f0890 100644
--- a/src/odr/document.hpp
+++ b/src/odr/document.hpp
@@ -19,7 +19,7 @@ class Element;
 class File;
 class Filesystem;
 
-/// @brief Represents a document.
+/// Represents a document.
 class Document final {
 public:
   explicit Document(std::shared_ptr<internal::abstract::Document>);
@@ -36,7 +36,7 @@ class Document final {
   void save(std::ostream &out) const;
   void save(std::ostream &out, const std::string &password) const;
 
-  /// @brief The saved document as a file in memory.
+  /// The saved document as a file in memory.
   [[nodiscard]] File save_to_memory() const;
   [[nodiscard]] File save_to_memory(const std::string &password) const;
 
diff --git a/src/odr/document_element.hpp b/src/odr/document_element.hpp
index bc478f499..6e5b3f9a8 100644
--- a/src/odr/document_element.hpp
+++ b/src/odr/document_element.hpp
@@ -77,7 +77,7 @@ class TableCell;
 class Frame;
 class Image;
 
-/// @brief Collection of element types.
+/// Collection of element types.
 enum class ElementType {
   none,
 
@@ -112,7 +112,7 @@ enum class ElementType {
   group,
 };
 
-/// @brief Collection of shapes a frame draws.
+/// Collection of shapes a frame draws.
 enum class ShapeType {
   none, ///< a plain box, drawing no outline of its own
   rect,
@@ -121,7 +121,7 @@ enum class ShapeType {
   custom, ///< an outline of its own, read from @ref Frame::path
 };
 
-/// @brief Collection of anchor types.
+/// Collection of anchor types.
 enum class AnchorType {
   as_char,
   at_char,
@@ -130,20 +130,20 @@ enum class AnchorType {
   at_paragraph,
 };
 
-/// @brief Collection of value types.
+/// Collection of value types.
 enum class ValueType {
   unknown,
   string,
   float_number,
 };
 
-/// @brief Collection of list types.
+/// Collection of list types.
 enum class ListType {
   unordered,
   ordered,
 };
 
-/// @brief Represents an element in a document.
+/// Represents an element in a document.
 class Element {
 public:
   Element();
@@ -206,7 +206,7 @@ class Element {
   [[nodiscard]] bool exists_() const;
 };
 
-/// @brief Represents an iterator for elements in a document.
+/// Represents an iterator for elements in a document.
 class ElementIterator {
 public:
   using value_type = Element;
@@ -243,7 +243,7 @@ class ElementIterator {
   [[nodiscard]] bool exists_() const;
 };
 
-/// @brief Represents a range of elements in a document.
+/// Represents a range of elements in a document.
 class ElementRange {
 public:
   ElementRange();
@@ -258,7 +258,7 @@ class ElementRange {
   ElementIterator m_end;
 };
 
-/// @brief Represents a typed element in a document.
+/// Represents a typed element in a document.
 template <typename T> class ElementBase : public Element {
 public:
   ElementBase() = default;
@@ -276,7 +276,7 @@ template <typename T> class ElementBase : public Element {
   }
 };
 
-/// @brief Represents a root element in a document.
+/// Represents a root element in a document.
 class TextRoot final : public ElementBase<internal::abstract::TextRootAdapter> {
 public:
   using ElementBase::ElementBase;
@@ -286,7 +286,7 @@ class TextRoot final : public ElementBase<internal::abstract::TextRootAdapter> {
   [[nodiscard]] MasterPage first_master_page() const;
 };
 
-/// @brief Represents a slide element in a document.
+/// Represents a slide element in a document.
 class Slide final : public ElementBase<internal::abstract::SlideAdapter> {
 public:
   using ElementBase::ElementBase;
@@ -298,7 +298,7 @@ class Slide final : public ElementBase<internal::abstract::SlideAdapter> {
   [[nodiscard]] MasterPage master_page() const;
 };
 
-/// @brief Represents a sheet element in a document.
+/// Represents a sheet element in a document.
 class Sheet final : public ElementBase<internal::abstract::SheetAdapter> {
 public:
   using ElementBase::ElementBase;
@@ -322,7 +322,7 @@ class Sheet final : public ElementBase<internal::abstract::SheetAdapter> {
                                           std::uint32_t row) const;
 };
 
-/// @brief Represents a sheet cell element in a document.
+/// Represents a sheet cell element in a document.
 class SheetCell final
     : public ElementBase<internal::abstract::SheetCellAdapter> {
 public:
@@ -334,7 +334,7 @@ class SheetCell final
   [[nodiscard]] ValueType value_type() const;
 };
 
-/// @brief Represents a page element in a document.
+/// Represents a page element in a document.
 class Page final : public ElementBase<internal::abstract::PageAdapter> {
 public:
   using ElementBase::ElementBase;
@@ -346,7 +346,7 @@ class Page final : public ElementBase<internal::abstract::PageAdapter> {
   [[nodiscard]] MasterPage master_page() const;
 };
 
-/// @brief Represents a master page element in a document.
+/// Represents a master page element in a document.
 class MasterPage final
     : public ElementBase<internal::abstract::MasterPageAdapter> {
 public:
@@ -355,7 +355,7 @@ class MasterPage final
   [[nodiscard]] PageLayout page_layout() const;
 };
 
-/// @brief Represents a line break element in a document.
+/// Represents a line break element in a document.
 class LineBreak final
     : public ElementBase<internal::abstract::LineBreakAdapter> {
 public:
@@ -364,7 +364,7 @@ class LineBreak final
   [[nodiscard]] TextStyle style() const;
 };
 
-/// @brief Represents a paragraph element in a document.
+/// Represents a paragraph element in a document.
 class Paragraph final
     : public ElementBase<internal::abstract::ParagraphAdapter> {
 public:
@@ -374,7 +374,7 @@ class Paragraph final
   [[nodiscard]] TextStyle text_style() const;
 };
 
-/// @brief Represents a span element in a document.
+/// Represents a span element in a document.
 class Span final : public ElementBase<internal::abstract::SpanAdapter> {
 public:
   using ElementBase::ElementBase;
@@ -382,7 +382,7 @@ class Span final : public ElementBase<internal::abstract::SpanAdapter> {
   [[nodiscard]] TextStyle style() const;
 };
 
-/// @brief Represents a text element in a document.
+/// Represents a text element in a document.
 class Text final : public ElementBase<internal::abstract::TextAdapter> {
 public:
   using ElementBase::ElementBase;
@@ -393,7 +393,7 @@ class Text final : public ElementBase<internal::abstract::TextAdapter> {
   [[nodiscard]] TextStyle style() const;
 };
 
-/// @brief Represents a link element in a document.
+/// Represents a link element in a document.
 class Link final : public ElementBase<internal::abstract::LinkAdapter> {
 public:
   using ElementBase::ElementBase;
@@ -401,7 +401,7 @@ class Link final : public ElementBase<internal::abstract::LinkAdapter> {
   [[nodiscard]] std::string href() const;
 };
 
-/// @brief Represents a bookmark element in a document.
+/// Represents a bookmark element in a document.
 class Bookmark final : public ElementBase<internal::abstract::BookmarkAdapter> {
 public:
   using ElementBase::ElementBase;
@@ -409,7 +409,7 @@ class Bookmark final : public ElementBase<internal::abstract::BookmarkAdapter> {
   [[nodiscard]] std::string name() const;
 };
 
-/// @brief Represents a list element in a document.
+/// Represents a list element in a document.
 class List final : public ElementBase<internal::abstract::ListAdapter> {
 public:
   using ElementBase::ElementBase;
@@ -417,7 +417,7 @@ class List final : public ElementBase<internal::abstract::ListAdapter> {
   [[nodiscard]] ListType type() const;
 };
 
-/// @brief Represents a list item element in a document.
+/// Represents a list item element in a document.
 class ListItem final : public ElementBase<internal::abstract::ListItemAdapter> {
 public:
   using ElementBase::ElementBase;
@@ -432,7 +432,7 @@ class ListItem final : public ElementBase<internal::abstract::ListItemAdapter> {
   [[nodiscard]] std::optional<std::uint32_t> number() const;
 };
 
-/// @brief Represents a table element in a document.
+/// Represents a table element in a document.
 class Table final : public ElementBase<internal::abstract::TableAdapter> {
 public:
   using ElementBase::ElementBase;
@@ -448,7 +448,7 @@ class Table final : public ElementBase<internal::abstract::TableAdapter> {
   [[nodiscard]] TableStyle style() const;
 };
 
-/// @brief Represents a table column element in a document.
+/// Represents a table column element in a document.
 class TableColumn final
     : public ElementBase<internal::abstract::TableColumnAdapter> {
 public:
@@ -457,7 +457,7 @@ class TableColumn final
   [[nodiscard]] TableColumnStyle style() const;
 };
 
-/// @brief Represents a table row element in a document.
+/// Represents a table row element in a document.
 class TableRow final : public ElementBase<internal::abstract::TableRowAdapter> {
 public:
   using ElementBase::ElementBase;
@@ -465,7 +465,7 @@ class TableRow final : public ElementBase<internal::abstract::TableRowAdapter> {
   [[nodiscard]] TableRowStyle style() const;
 };
 
-/// @brief Represents a table cell element in a document.
+/// Represents a table cell element in a document.
 class TableCell final
     : public ElementBase<internal::abstract::TableCellAdapter> {
 public:
@@ -490,7 +490,7 @@ struct DrawingPath final {
   double height{0};
 };
 
-/// @brief Represents the two ends of a line shape, in the parent's space.
+/// Represents the two ends of a line shape, in the parent's space.
 struct DrawingLine final {
   Measure x1{0, DynamicUnit()};
   Measure y1{0, DynamicUnit()};
@@ -512,7 +512,7 @@ struct DrawingTransform final {
   Measure f{0, DynamicUnit()};
 };
 
-/// @brief Represents a frame element in a document.
+/// Represents a frame element in a document.
 class Frame final : public ElementBase<internal::abstract::FrameAdapter> {
 public:
   using ElementBase::ElementBase;
@@ -533,7 +533,7 @@ class Frame final : public ElementBase<internal::abstract::FrameAdapter> {
   [[nodiscard]] GraphicStyle style() const;
 };
 
-/// @brief Represents an image element in a document.
+/// Represents an image element in a document.
 class Image final : public ElementBase<internal::abstract::ImageAdapter> {
 public:
   using ElementBase::ElementBase;
diff --git a/src/odr/document_path.hpp b/src/odr/document_path.hpp
index 1707d0ecf..14e3d90a6 100644
--- a/src/odr/document_path.hpp
+++ b/src/odr/document_path.hpp
@@ -10,7 +10,7 @@
 
 namespace odr {
 
-/// @brief A path to a specific element in a document.
+/// A path to a specific element in a document.
 class DocumentPath final {
 public:
   class Child final {
diff --git a/src/odr/exceptions.hpp b/src/odr/exceptions.hpp
index e5c838e46..87989aa5b 100644
--- a/src/odr/exceptions.hpp
+++ b/src/odr/exceptions.hpp
@@ -7,268 +7,268 @@ namespace odr {
 enum class FileType;
 enum class TextEncoding;
 
-/// @brief Base of every exception type this library declares. The decoders also
-/// throw plain `std::runtime_error` for malformed input with no dedicated type,
-/// so that remains the widest net.
+/// Base of every exception type this library declares. The decoders also throw
+/// plain `std::runtime_error` for malformed input with no dedicated type, so
+/// that remains the widest net.
 struct Exception : std::runtime_error {
   using std::runtime_error::runtime_error;
 };
 
-/// @brief Unsupported operation exception
+/// Unsupported operation exception
 struct UnsupportedOperation final : Exception {
   UnsupportedOperation();
   explicit UnsupportedOperation(const std::string &message);
 };
 
-/// @brief File not found exception
+/// File not found exception
 struct FileNotFound final : Exception {
   FileNotFound();
   explicit FileNotFound(const std::string &path);
 };
 
-/// @brief Unknown file type exception
+/// Unknown file type exception
 struct UnknownFileType final : Exception {
   UnknownFileType();
 };
 
-/// @brief Unsupported file type exception
+/// Unsupported file type exception
 struct UnsupportedFileType final : Exception {
   FileType file_type;
 
   explicit UnsupportedFileType(FileType file_type);
 };
 
-/// @brief Unsupported text encoding exception
+/// Unsupported text encoding exception
 struct UnsupportedTextEncoding final : Exception {
   TextEncoding text_encoding;
 
   explicit UnsupportedTextEncoding(TextEncoding text_encoding);
 };
 
-/// @brief File read error
+/// File read error
 struct FileReadError final : Exception {
   FileReadError();
 };
 
-/// @brief File write error
+/// File write error
 struct FileWriteError final : Exception {
   explicit FileWriteError(const std::string &path);
 };
 
-/// @brief No ZIP file exception base
+/// No ZIP file exception base
 struct NoZipFile final : Exception {
   NoZipFile();
 };
 
-/// @brief ZIP save error base; `internal::zip::MinizSaveError` refines it.
+/// ZIP save error base; `internal::zip::MinizSaveError` refines it.
 struct ZipSaveError : Exception {
   ZipSaveError();
 };
 
-/// @brief CFB error base; NoCfbFile and CfbFileCorrupted refine it.
+/// CFB error base; NoCfbFile and CfbFileCorrupted refine it.
 struct CfbError : Exception {
   explicit CfbError(const std::string &desc);
 };
 
-/// @brief No CFB file exception base
+/// No CFB file exception base
 struct NoCfbFile final : CfbError {
   NoCfbFile();
 };
 
-/// @brief CFB file corrupted exception base
+/// CFB file corrupted exception base
 struct CfbFileCorrupted final : CfbError {
   CfbFileCorrupted();
 };
 
-/// @brief No text file exception
+/// No text file exception
 struct NoTextFile final : Exception {
   NoTextFile();
 };
 
-/// @brief No csv file exception
+/// No csv file exception
 struct NoCsvFile final : Exception {
   NoCsvFile();
 };
 
-/// @brief No markdown file exception
+/// No markdown file exception
 struct NoMarkdownFile final : Exception {
   NoMarkdownFile();
 };
 
-/// @brief No json file exception
+/// No json file exception
 struct NoJsonFile final : Exception {
   NoJsonFile();
 };
 
-/// @brief No image file exception
+/// No image file exception
 struct NoImageFile final : Exception {
   NoImageFile();
 };
 
-/// @brief No archive file exception
+/// No archive file exception
 struct NoArchiveFile final : Exception {
   NoArchiveFile();
 };
 
-/// @brief No document file exception
+/// No document file exception
 struct NoDocumentFile final : Exception {
   NoDocumentFile();
 };
 
-/// @brief No open document file exception
+/// No open document file exception
 struct NoOpenDocumentFile final : Exception {
   NoOpenDocumentFile();
 };
 
-/// @brief No office open document file exception
+/// No office open document file exception
 struct NoOfficeOpenXmlFile final : Exception {
   NoOfficeOpenXmlFile();
 };
 
-/// @brief No PDF file exception
+/// No PDF file exception
 struct NoPdfFile final : Exception {
   NoPdfFile();
 };
 
-/// @brief No font file exception
+/// No font file exception
 struct NoFontFile final : Exception {
   NoFontFile();
 };
 
-/// @brief No legacy Microsoft Office file
+/// No legacy Microsoft Office file
 struct NoLegacyMicrosoftFile final : Exception {
   NoLegacyMicrosoftFile();
 };
 
-/// @brief No iWork file exception
+/// No iWork file exception
 struct NoIworkFile final : Exception {
   NoIworkFile();
 };
 
-/// @brief No XML file exception
+/// No XML file exception
 struct NoXmlFile final : Exception {
   NoXmlFile();
 };
 
-/// @brief No SVG file exception
+/// No SVG file exception
 struct NoSvgFile final : Exception {
   NoSvgFile();
 };
 
-/// @brief No RTF file exception
+/// No RTF file exception
 struct NoRtfFile final : Exception {
   NoRtfFile();
 };
 
-/// @brief Unsupported crypto algorithm exception
+/// Unsupported crypto algorithm exception
 struct UnsupportedCryptoAlgorithm final : Exception {
   UnsupportedCryptoAlgorithm();
 };
 
-/// @brief No SVM file exception base
+/// No SVM file exception base
 struct NoSvmFile final : Exception {
   NoSvmFile();
 };
 
-/// @brief Malformed SVM file exception base
+/// Malformed SVM file exception base
 struct MalformedSvmFile final : Exception {
   MalformedSvmFile();
 };
 
-/// @brief Unsupported endian exception
+/// Unsupported endian exception
 struct UnsupportedEndian final : Exception {
   UnsupportedEndian();
 };
 
-/// @brief Unsupported MS crypto algorithm exception
+/// Unsupported MS crypto algorithm exception
 struct MsUnsupportedCryptoAlgorithm final : Exception {
   MsUnsupportedCryptoAlgorithm();
 };
 
-/// @brief Unknown document type exception
+/// Unknown document type exception
 struct UnknownDocumentType final : Exception {
   UnknownDocumentType();
 };
 
-/// @brief Invalid prefix string
+/// Invalid prefix string
 struct InvalidPrefix final : Exception {
   InvalidPrefix();
   explicit InvalidPrefix(const std::string &prefix);
 };
 
-/// @brief Document copy protected exception
+/// Document copy protected exception
 struct DocumentCopyProtectedException final : Exception {
   DocumentCopyProtectedException();
 };
 
-/// @brief Resource is not accessible
+/// Resource is not accessible
 struct ResourceNotAccessible final : Exception {
   ResourceNotAccessible();
   ResourceNotAccessible(const std::string &name, const std::string &path);
 };
 
-/// @brief Prefix already in use
+/// Prefix already in use
 struct PrefixInUse final : Exception {
   PrefixInUse();
   explicit PrefixInUse(const std::string &prefix);
 };
 
-/// @brief HTTP server socket could not be bound
+/// HTTP server socket could not be bound
 struct ServerBindFailed final : Exception {
   ServerBindFailed(const std::string &host, std::uint32_t port);
 };
 
-/// @brief HTTP server is bound already
+/// HTTP server is bound already
 struct ServerAlreadyBound final : Exception {
   ServerAlreadyBound();
 };
 
-/// @brief HTTP server has not been bound
+/// HTTP server has not been bound
 struct ServerNotBound final : Exception {
   ServerNotBound();
 };
 
-/// @brief Unsupported option
+/// Unsupported option
 struct UnsupportedOption final : Exception {
   explicit UnsupportedOption(const std::string &message);
 };
 
-/// @brief Null pointer error
+/// Null pointer error
 struct NullPointerError final : Exception {
   explicit NullPointerError(const std::string &variable);
 };
 
-/// @brief Wrong password error
+/// Wrong password error
 struct WrongPasswordError final : Exception {
   explicit WrongPasswordError();
 };
 
-/// @brief Decryption failed
+/// Decryption failed
 struct DecryptionFailed final : Exception {
   explicit DecryptionFailed();
 };
 
-/// @brief Not encrypted error
+/// Not encrypted error
 struct NotEncryptedError final : Exception {
   explicit NotEncryptedError();
 };
 
-/// @brief Invalid path
+/// Invalid path
 struct InvalidPath final : Exception {
   explicit InvalidPath(const std::string &message);
 };
 
-/// @brief Unsupported file encoding
+/// Unsupported file encoding
 struct UnsupportedFileEncoding final : Exception {
   explicit UnsupportedFileEncoding(const std::string &message);
 };
 
-/// @brief File is encrypted
+/// File is encrypted
 struct FileEncryptedError final : Exception {
   explicit FileEncryptedError();
 };
 
-/// @brief Read attempted on an encrypted file that has not been authenticated
+/// Read attempted on an encrypted file that has not been authenticated
 struct UnauthenticatedReadError final : Exception {
   explicit UnauthenticatedReadError();
 };
diff --git a/src/odr/file.hpp b/src/odr/file.hpp
index 35fbcd1f2..07601b511 100644
--- a/src/odr/file.hpp
+++ b/src/odr/file.hpp
@@ -34,7 +34,7 @@ class FontFile;
 class Archive;
 class Document;
 
-/// @brief Collection of file types.
+/// Collection of file types.
 enum class FileType {
   unknown,
 
@@ -168,7 +168,7 @@ enum class FileType {
   hypertext_markup_language,
 };
 
-/// @brief Collection of file categories.
+/// Collection of file categories.
 enum class FileCategory {
   unknown,
   text,
@@ -181,7 +181,7 @@ enum class FileCategory {
   video,
 };
 
-/// @brief Collection of file locations.
+/// Collection of file locations.
 enum class FileLocation {
   unknown, ///< no file behind the handle
   memory,
@@ -206,7 +206,7 @@ struct FileTypeCapabilities final {
   bool encrypt{}; ///< @ref Document::save with a password is supported
 };
 
-/// @brief Collection of encryption states.
+/// Collection of encryption states.
 enum class EncryptionState {
   unknown,
   not_encrypted,
@@ -214,7 +214,7 @@ enum class EncryptionState {
   decrypted,
 };
 
-/// @brief Collection of document types.
+/// Collection of document types.
 enum class DocumentType {
   unknown,
   text,
@@ -301,9 +301,9 @@ struct DecodeOptions final {
   /// Format-specific overrides for a file decoded as csv.
   CsvOptions csv;
 
-  /// @brief Decode as exactly @p type, skipping detection.
+  /// Decode as exactly @p type, skipping detection.
   [[nodiscard]] static DecodeOptions as(FileType type);
-  /// @brief Decode as csv, reading it with @p options.
+  /// Decode as csv, reading it with @p options.
   [[nodiscard]] static DecodeOptions as_csv(const CsvOptions &options);
 };
 
@@ -331,10 +331,10 @@ struct FileMeta final {
   std::optional<std::string> modification_date;
 };
 
-/// @brief Represents a file.
+/// Represents a file.
 class File final {
 public:
-  /// @brief A file read from @p path on disk.
+  /// A file read from @p path on disk.
   [[nodiscard]] static File from_disk(const std::string &path);
   /// @brief A file held in memory; @p data is its bytes, moved in, @p name
   /// what it is called, if known.
@@ -349,7 +349,7 @@ class File final {
   File();
   /// @throws NullPointerError if the impl is null.
   explicit File(std::shared_ptr<internal::abstract::File>);
-  /// @brief Equivalent to @ref from_disk.
+  /// Equivalent to @ref from_disk.
   explicit File(const std::string &path);
 
   [[nodiscard]] FileLocation location() const noexcept;
@@ -372,7 +372,7 @@ class File final {
   std::shared_ptr<internal::abstract::File> m_impl;
 };
 
-/// @brief Represents a decoded file.
+/// Represents a decoded file.
 class DecodedFile {
 public:
   /// Decoding is @ref odr::open; this wraps what it produced.
@@ -419,18 +419,18 @@ class DecodedFile {
   std::shared_ptr<internal::abstract::DecodedFile> m_impl;
 };
 
-/// @brief Represents a text file.
+/// Represents a text file.
 class TextFile final : public DecodedFile {
 public:
   explicit TextFile(std::shared_ptr<internal::abstract::TextFile>);
 
-  /// @brief The encoding the file's bytes were detected as, or decoded with.
+  /// The encoding the file's bytes were detected as, or decoded with.
   [[nodiscard]] TextEncoding encoding() const;
 
-  /// @brief The file's bytes as they are.
+  /// The file's bytes as they are.
   [[nodiscard]] std::unique_ptr<std::istream> stream() const;
-  /// @brief The file's text, decoded to UTF-8 where @ref encoding is
-  /// decodable, and the raw bytes where it is not.
+  /// The file's text, decoded to UTF-8 where @ref encoding is decodable, and
+  /// the raw bytes where it is not.
   [[nodiscard]] std::string text() const;
 
   [[nodiscard]] std::shared_ptr<internal::abstract::TextFile> impl() const;
@@ -439,17 +439,17 @@ class TextFile final : public DecodedFile {
   std::shared_ptr<internal::abstract::TextFile> m_impl;
 };
 
-/// @brief Represents a csv file.
+/// Represents a csv file.
 class CsvFile final : public DecodedFile {
 public:
   explicit CsvFile(std::shared_ptr<internal::abstract::CsvFile>);
 
-  /// @brief The csv as a one-sheet spreadsheet. The other view of the same
-  /// bytes — a csv stays a text file, so @ref TextFile::text still works.
+  /// The csv as a one-sheet spreadsheet. The other view of the same bytes — a
+  /// csv stays a text file, so @ref TextFile::text still works.
   /// @throws UnsupportedTextEncoding if the encoding cannot be decoded.
   [[nodiscard]] Document document() const;
 
-  /// @brief The options in use, every field resolved.
+  /// The options in use, every field resolved.
   [[nodiscard]] CsvOptions options() const;
 
   [[nodiscard]] std::shared_ptr<internal::abstract::CsvFile> impl() const;
@@ -458,12 +458,12 @@ class CsvFile final : public DecodedFile {
   std::shared_ptr<internal::abstract::CsvFile> m_impl;
 };
 
-/// @brief Represents a markdown file.
+/// Represents a markdown file.
 class MarkdownFile final : public DecodedFile {
 public:
   explicit MarkdownFile(std::shared_ptr<internal::abstract::MarkdownFile>);
 
-  /// @brief The markdown as a text document. The other view of the same bytes —
+  /// The markdown as a text document. The other view of the same bytes —
   /// markdown stays a text file, so @ref TextFile::text still works.
   /// @throws UnsupportedTextEncoding if the encoding cannot be decoded.
   [[nodiscard]] Document document() const;
@@ -474,7 +474,7 @@ class MarkdownFile final : public DecodedFile {
   std::shared_ptr<internal::abstract::MarkdownFile> m_impl;
 };
 
-/// @brief Represents an image file.
+/// Represents an image file.
 class ImageFile final : public DecodedFile {
 public:
   explicit ImageFile(std::shared_ptr<internal::abstract::ImageFile>);
@@ -485,7 +485,7 @@ class ImageFile final : public DecodedFile {
   std::shared_ptr<internal::abstract::ImageFile> m_impl;
 };
 
-/// @brief Represents an archive file.
+/// Represents an archive file.
 class ArchiveFile final : public DecodedFile {
 public:
   explicit ArchiveFile(std::shared_ptr<internal::abstract::ArchiveFile>);
@@ -496,7 +496,7 @@ class ArchiveFile final : public DecodedFile {
   std::shared_ptr<internal::abstract::ArchiveFile> m_impl;
 };
 
-/// @brief Represents a document file.
+/// Represents a document file.
 class DocumentFile final : public DecodedFile {
 public:
   /// Narrowing is @ref DecodedFile::as_document_file; this wraps its result.
@@ -521,7 +521,7 @@ class DocumentFile final : public DecodedFile {
   std::shared_ptr<internal::abstract::DocumentFile> m_impl;
 };
 
-/// @brief Represents a PDF file.
+/// Represents a PDF file.
 class PdfFile final : public DecodedFile {
 public:
   explicit PdfFile(std::shared_ptr<internal::abstract::PdfFile>);
@@ -534,7 +534,7 @@ class PdfFile final : public DecodedFile {
   std::shared_ptr<internal::abstract::PdfFile> m_impl;
 };
 
-/// @brief Represents a font file.
+/// Represents a font file.
 class FontFile final : public DecodedFile {
 public:
   explicit FontFile(std::shared_ptr<internal::abstract::FontFile>);
diff --git a/src/odr/filesystem.hpp b/src/odr/filesystem.hpp
index 9fcf82e3e..11106ff23 100644
--- a/src/odr/filesystem.hpp
+++ b/src/odr/filesystem.hpp
@@ -11,7 +11,7 @@ class ReadableFilesystem;
 namespace odr {
 class File;
 
-/// @brief FileWalker class
+/// FileWalker class
 class FileWalker {
 public:
   explicit FileWalker(std::unique_ptr<internal::abstract::FileWalker>);
@@ -36,7 +36,7 @@ class FileWalker {
   std::unique_ptr<internal::abstract::FileWalker> m_impl;
 };
 
-/// @brief Filesystem class
+/// Filesystem class
 class Filesystem {
 public:
   explicit Filesystem(std::shared_ptr<internal::abstract::ReadableFilesystem>);
diff --git a/src/odr/font.hpp b/src/odr/font.hpp
index 7fa7e4b36..46aed0310 100644
--- a/src/odr/font.hpp
+++ b/src/odr/font.hpp
@@ -4,7 +4,7 @@
 
 namespace odr {
 
-/// @brief Source flavor of a font program.
+/// Source flavor of a font program.
 enum class FontFormat {
   unknown,
   truetype,     ///< SFNT with `glyf` outlines (incl. CIDFontType2)
@@ -13,7 +13,7 @@ enum class FontFormat {
   type1,        ///< Type1 / `eexec`
 };
 
-/// @brief Glyph-space bounding box, in font design units.
+/// Glyph-space bounding box, in font design units.
 struct FontBBox {
   std::int16_t x_min{};
   std::int16_t y_min{};
diff --git a/src/odr/html.hpp b/src/odr/html.hpp
index 7444e34bb..4e2922632 100644
--- a/src/odr/html.hpp
+++ b/src/odr/html.hpp
@@ -67,14 +67,14 @@ using HtmlResourceLocator = std::function<HtmlResourceLocation(
 using HtmlResources =
     std::vector<std::pair<HtmlResource, HtmlResourceLocation>>;
 
-/// @brief HTML table gridlines.
+/// HTML table gridlines.
 enum class HtmlTableGridlines {
   none,
   soft,
   hard,
 };
 
-/// @brief The colors the emitted HTML renders against. @ref
+/// The colors the emitted HTML renders against. @ref
 /// FileTypeCapabilities::color_scheme says which views honor it.
 enum class HtmlColorScheme {
   light,  ///< a white page, carrying the colors the document gives its content
@@ -82,8 +82,8 @@ enum class HtmlColorScheme {
   system, ///< `light` or `dark`, by the reader's `prefers-color-scheme`
 };
 
-/// @brief The zoom a view opens at, and who fits it: the browser through the
-/// viewport meta tag, which desktop browsers ignore, or the view itself.
+/// The zoom a view opens at, and who fits it: the browser through the viewport
+/// meta tag, which desktop browsers ignore, or the view itself.
 enum class HtmlViewportMode {
   automatic,   ///< `fit_width` for fixed-size paged content (PDF pages, slides,
                ///< drawings, images, text documents with page margins),
@@ -97,8 +97,7 @@ enum class HtmlViewportMode {
   fit_width_by_view,
 };
 
-/// @brief How text is emitted in PDF→HTML output. Neither mode needs
-/// JavaScript.
+/// How text is emitted in PDF→HTML output. Neither mode needs JavaScript.
 enum class PdfTextMode {
   dual_layer,   ///< a visual layer (paint order, embedded PUA glyphs) plus a
                 ///< transparent selection layer (reading order, real Unicode),
@@ -107,7 +106,7 @@ enum class PdfTextMode {
                 ///< analysis, like pdf2htmlEX
 };
 
-/// @brief HTML configuration.
+/// HTML configuration.
 struct HtmlConfig {
   /// File name for the view that writes the whole document.
   std::string document_output_file_name{"document.html"};
@@ -293,17 +292,17 @@ namespace html {
 
 HtmlResourceLocator standard_resource_locator();
 
-/// @brief Translates a decoded file to HTML, dispatching on the decoded type.
+/// Translates a decoded file to HTML, dispatching on the decoded type.
 HtmlService translate(const DecodedFile &file, const HtmlConfig &config,
                       const Logger &logger = Logger::null());
 
-/// @brief Translates a document to HTML.
+/// Translates a document to HTML.
 HtmlService translate(const Document &document, const HtmlConfig &config,
                       const Logger &logger = Logger::null());
-/// @brief Translates a filesystem to HTML.
+/// Translates a filesystem to HTML.
 HtmlService translate(const Filesystem &filesystem, const HtmlConfig &config,
                       const Logger &logger = Logger::null());
-/// @brief Translates an archive to HTML.
+/// Translates an archive to HTML.
 HtmlService translate(const Archive &archive, const HtmlConfig &config,
                       const Logger &logger = Logger::null());
 
diff --git a/src/odr/logger.hpp b/src/odr/logger.hpp
index 514928d43..d6c3c1d2d 100644
--- a/src/odr/logger.hpp
+++ b/src/odr/logger.hpp
@@ -53,7 +53,7 @@ class Logger final {
   using Clock = ILogger::Clock;
   using Time = ILogger::Time;
 
-  /// @brief A logger discarding everything. All instances share one sink.
+  /// A logger discarding everything. All instances share one sink.
   static Logger null();
   static Logger create_stdio(const std::string &name, LogLevel level,
                              const LogFormat &format = LogFormat(),
@@ -66,7 +66,7 @@ class Logger final {
                          const std::source_location &location,
                          const LogFormat &format);
 
-  /// @brief Constructs the null logger.
+  /// Constructs the null logger.
   Logger();
   explicit Logger(std::shared_ptr<ILogger> impl);
 
diff --git a/src/odr/odr.hpp b/src/odr/odr.hpp
index 9d81c9491..c6fb3a0cc 100644
--- a/src/odr/odr.hpp
+++ b/src/odr/odr.hpp
@@ -10,22 +10,22 @@
 
 namespace odr {
 
-/// @brief The version of the library.
+/// The version of the library.
 [[nodiscard]] std::string version();
-/// @brief The commit the library was built from.
+/// The commit the library was built from.
 [[nodiscard]] std::string commit_hash();
-/// @brief Whether that commit had uncommitted changes.
+/// Whether that commit had uncommitted changes.
 [[nodiscard]] bool is_dirty() noexcept;
-/// @brief Whether the library is built in debug mode.
+/// Whether the library is built in debug mode.
 [[nodiscard]] bool is_debug() noexcept;
-/// @brief All of the above in one string.
+/// All of the above in one string.
 [[nodiscard]] std::string identify() noexcept;
 
-/// @brief Every file type this library knows about, in declaration order,
-/// including @ref FileType::unknown.
+/// Every file type this library knows about, in declaration order, including
+/// @ref FileType::unknown.
 [[nodiscard]] std::vector<FileType> all_file_types();
 
-/// @brief The file type for a file extension, @ref FileType::unknown if none.
+/// The file type for a file extension, @ref FileType::unknown if none.
 [[nodiscard]] FileType
 file_type_by_file_extension(const std::string &extension) noexcept;
 /// @brief Every file extension accepted for the file type, without a leading
@@ -36,39 +36,39 @@ file_type_by_file_extension(const std::string &extension) noexcept;
 /// `docx`/`pptx`/`xlsx` file.
 [[nodiscard]] std::span<const std::string_view>
 file_extensions_by_file_type(FileType type) noexcept;
-/// @brief The canonical file extension, without a leading dot.
+/// The canonical file extension, without a leading dot.
 /// @throws UnsupportedFileType if the type has none.
 [[nodiscard]] std::string_view file_extension_by_file_type(FileType type);
-/// @brief The file category the file type belongs to.
+/// The file category the file type belongs to.
 [[nodiscard]] FileCategory file_category_by_file_type(FileType type) noexcept;
-/// @brief The document type the file type carries, if any.
+/// The document type the file type carries, if any.
 [[nodiscard]] DocumentType document_type_by_file_type(FileType type) noexcept;
-/// @brief The file type's name.
+/// The file type's name.
 [[nodiscard]] std::string file_type_to_string(FileType type);
-/// @brief The file category's name.
+/// The file category's name.
 [[nodiscard]] std::string file_category_to_string(FileCategory type);
-/// @brief The document type's name.
+/// The document type's name.
 [[nodiscard]] std::string document_type_to_string(DocumentType type);
-/// @brief The file type for a MIME type, @ref FileType::unknown if none.
+/// The file type for a MIME type, @ref FileType::unknown if none.
 [[nodiscard]] FileType
 file_type_by_mimetype(std::string_view mimetype) noexcept;
-/// @brief The canonical MIME type.
+/// The canonical MIME type.
 /// @throws UnsupportedFileType if the type has none.
 [[nodiscard]] std::string_view mimetype_by_file_type(FileType type);
-/// @brief Every MIME type accepted for the file type, canonical one first.
+/// Every MIME type accepted for the file type, canonical one first.
 [[nodiscard]] std::span<const std::string_view>
 mimetypes_by_file_type(FileType type) noexcept;
 
-/// @brief What this library can do with the file type: format-level support,
-/// i.e. an upper bound — see @ref FileTypeCapabilities.
+/// What this library can do with the file type: format-level support, i.e. an
+/// upper bound — see @ref FileTypeCapabilities.
 [[nodiscard]] FileTypeCapabilities
 capabilities_by_file_type(FileType type) noexcept;
 
-/// @brief Every text encoding this library knows about, in declaration order,
+/// Every text encoding this library knows about, in declaration order,
 /// excluding @ref TextEncoding::unknown.
 [[nodiscard]] std::vector<TextEncoding> all_text_encodings();
 
-/// @brief The text encoding's canonical name, a label a browser accepts.
+/// The text encoding's canonical name, a label a browser accepts.
 /// @throws UnsupportedTextEncoding for @ref TextEncoding::unknown.
 [[nodiscard]] std::string_view text_encoding_to_string(TextEncoding encoding);
 /// @brief The text encoding for a name, @ref TextEncoding::unknown if none.
@@ -77,23 +77,23 @@ capabilities_by_file_type(FileType type) noexcept;
 /// `WINDOWS_1252` and `cp1252` all name the same encoding.
 [[nodiscard]] TextEncoding
 text_encoding_by_name(std::string_view name) noexcept;
-/// @brief Every name accepted for the text encoding, canonical one first.
+/// Every name accepted for the text encoding, canonical one first.
 [[nodiscard]] std::span<const std::string_view>
 text_encoding_names(TextEncoding encoding) noexcept;
-/// @brief Whether the library can decode the text encoding, as opposed to
-/// merely naming it.
+/// Whether the library can decode the text encoding, as opposed to merely
+/// naming it.
 [[nodiscard]] bool text_encoding_is_decodable(TextEncoding encoding) noexcept;
 
-/// @brief The file types detected for @p file.
+/// The file types detected for @p file.
 [[nodiscard]] std::vector<FileType>
 list_file_types(const File &file, const Logger &logger = Logger::null());
-/// @brief The file types detected for the file at @p path.
+/// The file types detected for the file at @p path.
 [[nodiscard]] std::vector<FileType>
 list_file_types(const std::string &path, const Logger &logger = Logger::null());
-/// @brief The MIME type detected for @p file.
+/// The MIME type detected for @p file.
 [[nodiscard]] std::string_view mimetype(const File &file,
                                         const Logger &logger = Logger::null());
-/// @brief The MIME type detected for the file at @p path.
+/// The MIME type detected for the file at @p path.
 [[nodiscard]] std::string_view mimetype(const std::string &path,
                                         const Logger &logger = Logger::null());
 
@@ -106,7 +106,7 @@ list_file_types(const std::string &path, const Logger &logger = Logger::null());
 [[nodiscard]] DecodedFile open(const File &file,
                                const DecodeOptions &options = {},
                                const Logger &logger = Logger::null());
-/// @brief Opens and decodes the file at @p path, per @p options.
+/// Opens and decodes the file at @p path, per @p options.
 [[nodiscard]] DecodedFile open(const std::string &path,
                                const DecodeOptions &options = {},
                                const Logger &logger = Logger::null());
diff --git a/src/odr/quantity.hpp b/src/odr/quantity.hpp
index b41e1487e..ef9d168e5 100644
--- a/src/odr/quantity.hpp
+++ b/src/odr/quantity.hpp
@@ -9,7 +9,7 @@
 
 namespace odr {
 
-/// @brief Represents a runtime unit of measure.
+/// Represents a runtime unit of measure.
 class DynamicUnit {
 public:
   /// Constructs the unitless unit, equal to `DynamicUnit("")`.
@@ -31,15 +31,15 @@ class DynamicUnit {
   const Unit *m_unit{nullptr};
 };
 
-/// @brief The magnitude-type-independent part of @ref Quantity, so it can be
-/// compiled once in a source file instead of inline in every instantiation.
+/// The magnitude-type-independent part of @ref Quantity, so it can be compiled
+/// once in a source file instead of inline in every instantiation.
 class QuantityBase {
 protected:
   /// Renders @p magnitude with 7 significant digits, always positional.
   static std::string format_magnitude(double magnitude);
 };
 
-/// @brief Represents a quantity with a magnitude and a unit of measure.
+/// Represents a quantity with a magnitude and a unit of measure.
 template <typename Magnitude, typename Unit = DynamicUnit>
 class Quantity : private QuantityBase {
 public:
@@ -87,7 +87,7 @@ class Quantity : private QuantityBase {
   Unit m_unit;
 };
 
-/// @brief Represents a quantity: a magnitude and a unit of measure.
+/// Represents a quantity: a magnitude and a unit of measure.
 using Measure = Quantity<double>;
 
 } // namespace odr
diff --git a/src/odr/style.hpp b/src/odr/style.hpp
index 32a9cc68d..21bfa639f 100644
--- a/src/odr/style.hpp
+++ b/src/odr/style.hpp
@@ -10,19 +10,19 @@
 
 namespace odr {
 
-/// @brief Collection of font weights.
+/// Collection of font weights.
 enum class FontWeight {
   normal,
   bold,
 };
 
-/// @brief Collection of font styles.
+/// Collection of font styles.
 enum class FontStyle {
   normal,
   italic,
 };
 
-/// @brief Collection of vertical font positions (sub/superscript).
+/// Collection of vertical font positions (sub/superscript).
 enum class FontPosition {
   normal,
   super,
@@ -50,14 +50,14 @@ enum class TextDirection {
   right_to_left,
 };
 
-/// @brief Collection of horizontal alignments.
+/// Collection of horizontal alignments.
 enum class HorizontalAlign {
   left,
   center,
   right,
 };
 
-/// @brief Collection of vertical alignments.
+/// Collection of vertical alignments.
 enum class VerticalAlign {
   top,
   middle,
@@ -75,13 +75,13 @@ enum class BreakType {
   column,
 };
 
-/// @brief Collection of print orientations.
+/// Collection of print orientations.
 enum class PrintOrientation {
   portrait,
   landscape,
 };
 
-/// @brief Collection of text wrapping options.
+/// Collection of text wrapping options.
 enum class TextWrap {
   none,
   before,
@@ -89,16 +89,16 @@ enum class TextWrap {
   run_through,
 };
 
-/// @brief Represents a color.
+/// Represents a color.
 struct Color final {
   std::uint8_t red{0};
   std::uint8_t green{0};
   std::uint8_t blue{0};
   std::uint8_t alpha{255};
 
-  /// @brief Builds an opaque color from a packed `0xRRGGBB` value.
+  /// Builds an opaque color from a packed `0xRRGGBB` value.
   static Color from_rgb(std::uint32_t rgb);
-  /// @brief Builds a color from a packed `0xAARRGGBB` value.
+  /// Builds a color from a packed `0xAARRGGBB` value.
   static Color from_argb(std::uint32_t argb);
 
   Color();
@@ -114,7 +114,7 @@ inline Color operator""_rgb(const unsigned long long rgb) {
   return Color::from_rgb(static_cast<std::uint32_t>(rgb));
 }
 
-/// @brief Represents a directional style.
+/// Represents a directional style.
 template <typename T> struct DirectionalStyle final {
   std::optional<T> right;
   std::optional<T> top;
@@ -175,7 +175,7 @@ struct TextStyle final {
   void override(const TextStyle &other);
 };
 
-/// @brief Represents a style for paragraphs.
+/// Represents a style for paragraphs.
 struct ParagraphStyle final {
   std::optional<TextAlign> text_align;
   /// The base direction the paragraph's text runs in.
@@ -190,7 +190,7 @@ struct ParagraphStyle final {
   void override(const ParagraphStyle &other);
 };
 
-/// @brief Represents a style for tables.
+/// Represents a style for tables.
 struct TableStyle final {
   std::optional<Measure> width;
   /// The frame around the table, and the rules between its rows and columns.
@@ -203,21 +203,21 @@ struct TableStyle final {
   void override(const TableStyle &other);
 };
 
-/// @brief Represents a style for table columns.
+/// Represents a style for table columns.
 struct TableColumnStyle final {
   std::optional<Measure> width;
 
   void override(const TableColumnStyle &other);
 };
 
-/// @brief Represents a style for table rows.
+/// Represents a style for table rows.
 struct TableRowStyle final {
   std::optional<Measure> height;
 
   void override(const TableRowStyle &other);
 };
 
-/// @brief Represents a style for table cells.
+/// Represents a style for table cells.
 struct TableCellStyle final {
   std::optional<HorizontalAlign> horizontal_align;
   std::optional<VerticalAlign> vertical_align;
@@ -232,7 +232,7 @@ struct TableCellStyle final {
   void override(const TableCellStyle &other);
 };
 
-/// @brief Represents a style for graphics.
+/// Represents a style for graphics.
 struct GraphicStyle final {
   std::optional<Measure> stroke_width;
   std::optional<Color> stroke_color;
@@ -245,7 +245,7 @@ struct GraphicStyle final {
   void override(const GraphicStyle &other);
 };
 
-/// @brief Represents a layout for a page.
+/// Represents a layout for a page.
 struct PageLayout final {
   std::optional<Measure> width;
   std::optional<Measure> height;
diff --git a/src/odr/table_dimension.hpp b/src/odr/table_dimension.hpp
index a346c9921..8d0516afa 100644
--- a/src/odr/table_dimension.hpp
+++ b/src/odr/table_dimension.hpp
@@ -4,7 +4,7 @@
 
 namespace odr {
 
-/// @brief Represents the dimensions of a table.
+/// Represents the dimensions of a table.
 struct TableDimensions {
   std::uint32_t rows{0};
   std::uint32_t columns{0};