From 15c4301136efd8fd7295aacfb7dd665460d5c3ed Mon Sep 17 00:00:00 2001 From: Andreas Stefl Date: Sun, 6 Sep 2026 15:22:23 +0200 Subject: [PATCH] docs(api): drop @brief where it is the only description 196 doc comments in the public headers opened with @brief and 174 of them had nothing under it, so the tag marked nothing off from anything - it read as ceremony rather than structure. 68 blocks already went without it, so the headers were inconsistent about it too, and there is no Doxyfile in the tree for the distinction to feed. The 22 that do carry a detail paragraph keep it, which is the line the rule added to AGENTS.md draws: write the description plainly, add @brief at the moment a second paragraph arrives. Paragraphs whose first line lost the seven characters are rewrapped, so the change adds no ragged wrapping. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_012QiYawTVZyuMLQBQngdTeu --- AGENTS.md | 3 + src/odr/archive.hpp | 2 +- src/odr/document.hpp | 4 +- src/odr/document_element.hpp | 60 ++++++++++---------- src/odr/document_path.hpp | 2 +- src/odr/exceptions.hpp | 106 +++++++++++++++++------------------ src/odr/file.hpp | 54 +++++++++--------- src/odr/filesystem.hpp | 4 +- src/odr/font.hpp | 4 +- src/odr/html.hpp | 21 ++++--- src/odr/logger.hpp | 4 +- src/odr/odr.hpp | 58 +++++++++---------- src/odr/quantity.hpp | 10 ++-- src/odr/style.hpp | 36 ++++++------ src/odr/table_dimension.hpp | 2 +- 15 files changed, 186 insertions(+), 184 deletions(-) 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); 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); @@ -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 class ElementBase : public Element { public: ElementBase() = default; @@ -276,7 +276,7 @@ template class ElementBase : public Element { } }; -/// @brief Represents a root element in a document. +/// Represents a root element in a document. class TextRoot final : public ElementBase { public: using ElementBase::ElementBase; @@ -286,7 +286,7 @@ class TextRoot final : public ElementBase { [[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 { public: using ElementBase::ElementBase; @@ -298,7 +298,7 @@ class Slide final : public ElementBase { [[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 { public: using ElementBase::ElementBase; @@ -322,7 +322,7 @@ class Sheet final : public ElementBase { 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 { 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 { public: using ElementBase::ElementBase; @@ -346,7 +346,7 @@ class Page final : public ElementBase { [[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 { 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 { 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 { 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 { public: using ElementBase::ElementBase; @@ -382,7 +382,7 @@ class Span final : public ElementBase { [[nodiscard]] TextStyle style() const; }; -/// @brief Represents a text element in a document. +/// Represents a text element in a document. class Text final : public ElementBase { public: using ElementBase::ElementBase; @@ -393,7 +393,7 @@ class Text final : public ElementBase { [[nodiscard]] TextStyle style() const; }; -/// @brief Represents a link element in a document. +/// Represents a link element in a document. class Link final : public ElementBase { public: using ElementBase::ElementBase; @@ -401,7 +401,7 @@ class Link final : public ElementBase { [[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 { public: using ElementBase::ElementBase; @@ -409,7 +409,7 @@ class Bookmark final : public ElementBase { [[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 { public: using ElementBase::ElementBase; @@ -417,7 +417,7 @@ class List final : public ElementBase { [[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 { public: using ElementBase::ElementBase; @@ -432,7 +432,7 @@ class ListItem final : public ElementBase { [[nodiscard]] std::optional number() const; }; -/// @brief Represents a table element in a document. +/// Represents a table element in a document. class Table final : public ElementBase { public: using ElementBase::ElementBase; @@ -448,7 +448,7 @@ class Table final : public ElementBase { [[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 { 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 { public: using ElementBase::ElementBase; @@ -465,7 +465,7 @@ class TableRow final : public ElementBase { [[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 { 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 { public: using ElementBase::ElementBase; @@ -533,7 +533,7 @@ class Frame final : public ElementBase { [[nodiscard]] GraphicStyle style() const; }; -/// @brief Represents an image element in a document. +/// Represents an image element in a document. class Image final : public ElementBase { 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 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); - /// @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 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 m_impl; }; -/// @brief Represents a text file. +/// Represents a text file. class TextFile final : public DecodedFile { public: explicit TextFile(std::shared_ptr); - /// @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 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 impl() const; @@ -439,17 +439,17 @@ class TextFile final : public DecodedFile { std::shared_ptr m_impl; }; -/// @brief Represents a csv file. +/// Represents a csv file. class CsvFile final : public DecodedFile { public: explicit CsvFile(std::shared_ptr); - /// @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 impl() const; @@ -458,12 +458,12 @@ class CsvFile final : public DecodedFile { std::shared_ptr m_impl; }; -/// @brief Represents a markdown file. +/// Represents a markdown file. class MarkdownFile final : public DecodedFile { public: explicit MarkdownFile(std::shared_ptr); - /// @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 m_impl; }; -/// @brief Represents an image file. +/// Represents an image file. class ImageFile final : public DecodedFile { public: explicit ImageFile(std::shared_ptr); @@ -485,7 +485,7 @@ class ImageFile final : public DecodedFile { std::shared_ptr m_impl; }; -/// @brief Represents an archive file. +/// Represents an archive file. class ArchiveFile final : public DecodedFile { public: explicit ArchiveFile(std::shared_ptr); @@ -496,7 +496,7 @@ class ArchiveFile final : public DecodedFile { std::shared_ptr 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 m_impl; }; -/// @brief Represents a PDF file. +/// Represents a PDF file. class PdfFile final : public DecodedFile { public: explicit PdfFile(std::shared_ptr); @@ -534,7 +534,7 @@ class PdfFile final : public DecodedFile { std::shared_ptr m_impl; }; -/// @brief Represents a font file. +/// Represents a font file. class FontFile final : public DecodedFile { public: explicit FontFile(std::shared_ptr); 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); @@ -36,7 +36,7 @@ class FileWalker { std::unique_ptr m_impl; }; -/// @brief Filesystem class +/// Filesystem class class Filesystem { public: explicit Filesystem(std::shared_ptr); 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>; -/// @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 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 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 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 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 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 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 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 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 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; } // 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(rgb)); } -/// @brief Represents a directional style. +/// Represents a directional style. template struct DirectionalStyle final { std::optional right; std::optional 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 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 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 width; void override(const TableColumnStyle &other); }; -/// @brief Represents a style for table rows. +/// Represents a style for table rows. struct TableRowStyle final { std::optional height; void override(const TableRowStyle &other); }; -/// @brief Represents a style for table cells. +/// Represents a style for table cells. struct TableCellStyle final { std::optional horizontal_align; std::optional 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 stroke_width; std::optional 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 width; std::optional 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};