feat(model)!: date precision via ModelDate + optional dates, drop epoch sentinel

Every date field (release_time/update_time across manga/anime/image, plus
AiredStatus and Comment) becomes std::optional<ModelDate>. ModelDate pairs the
instant with a DatePrecision (Day/Month/Quarter/Year): a source that knows only a
year (or an anime season) pins the instant to that bucket's first day and marks the
precision, so a consumer renders "2025" / a season instead of a fabricated 1 January.
An absent date is nullopt — the unknown_time epoch sentinel is removed.

Also takes the doxygen build to zero warnings: qualifies @ref targets with the
aniparse:: namespace (ModelDate, and the pre-existing url_encode / Parser::auth_info /
AuthKeys / AuthenticationData / total_chapters / Tag::axis) and drops a stray colon.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Toilettrauma

include/aniparse/anime/AnimeModel.hpp

@@ -32,7 +32,7 @@
  *
  * It parallels the manga model deliberately (episodes for chapters, playable sources
  * for pages) and follows the same two rules: an absent value (an empty string, a
- * nullopt, @ref aniparse::unknown_time) means the source did not state it in that
+ * nullopt, @c nullopt) means the source did not state it in that
  * response, not that the anime lacks it; and identity is the opaque handle
  * (AnimeEpisodeInfo::ref()), not the episode number, which is for display.
  *
@@ -135,12 +135,12 @@ struct AnimeInfo {
 	AiredStatus status;
 
 	/// When the anime was last touched on the source (a new episode, an edit).
-	/// @ref aniparse::unknown_time = not stated. Orders items within one source only, since
+	/// @c nullopt = not stated. Orders items within one source only, since
 	/// sources differ on what counts as an update.
-	std::chrono::system_clock::time_point update_time  = unknown_time;
-	/// When it first aired. @ref aniparse::unknown_time = the source states no exact date —
+	std::optional<ModelDate> update_time;
+	/// When it first aired. @c nullopt = the source states no exact date —
 	/// common, since many sources give only @ref season and @ref year.
-	std::chrono::system_clock::time_point release_time = unknown_time;
+	std::optional<ModelDate> release_time;
 
 	/// Opaque change marker for the whole anime; @see MangaInfo::revision.
 	std::string revision;
@@ -258,11 +258,11 @@ struct AnimeEpisodeInfo {
 	/// descriptors, not the video — that comes from episode_sources(). @see Image
 	std::vector<Image> previews;
 	/// When the episode entry was last edited/re-uploaded on the source;
-	/// @ref aniparse::unknown_time = not stated.
-	std::chrono::system_clock::time_point update_time  = unknown_time;
-	/// When the episode aired or was posted; @ref aniparse::unknown_time = not stated. Sources
+	/// @c nullopt = not stated.
+	std::optional<ModelDate> update_time;
+	/// When the episode aired or was posted; @c nullopt = not stated. Sources
 	/// differ on which of the two they report, so it dates the entry, not the broadcast.
-	std::chrono::system_clock::time_point release_time = unknown_time;
+	std::optional<ModelDate> release_time;
 
 	/**
 	 * @brief Identity for the episode_sources() round-trip.

include/aniparse/images/ImageModel.hpp

@@ -33,7 +33,7 @@
  * holding a single item and the other many. The items are not necessarily still
  * pictures, so each declares its own @ref aniparse::ImageItemKind. Absent values
  * follow the model-wide rule: an empty string, a nullopt or
- * @ref aniparse::unknown_time means the source did not state it.
+ * @c nullopt means the source did not state it.
  */
 
 namespace aniparse {
@@ -128,12 +128,12 @@ struct ImageContainerInfo {
 	/// View counters. nullopt = the source publishes none. @see ViewStats
 	std::optional<ViewStats> views;
 
-	/// When the container was last changed on the source. @ref aniparse::unknown_time = not
+	/// When the container was last changed on the source. @c nullopt = not
 	/// stated. For change detection prefer @ref revision, which is defined for
 	/// equality comparison; this field is for display.
-	std::chrono::system_clock::time_point update_time  = unknown_time;
-	/// When the container was posted. @ref aniparse::unknown_time = the source does not state it.
-	std::chrono::system_clock::time_point release_time = unknown_time;
+	std::optional<ModelDate> update_time;
+	/// When the container was posted. @c nullopt = the source does not state it.
+	std::optional<ModelDate> release_time;
 
 	/// Opaque change marker for the whole container; @see MangaInfo::revision.
 	std::string revision;

include/aniparse/manga/MangaModel.hpp

@@ -30,7 +30,7 @@
  * field here; the getters do the fetching, these types only carry what came back.
  *
  * Two rules run through the file. An absent value (an empty string, a nullopt,
- * @ref aniparse::unknown_time) means the source did not state it in that response,
+ * @c nullopt) means the source did not state it in that response,
  * never that the manga lacks it — the same struct is filled shallowly for a search
  * card and fully for a detail fetch. And identity is the opaque handle, not the
  * numbers: a chapter is addressed by MangaChapterInfo::ref(), not by its volume and
@@ -137,12 +137,12 @@ struct MangaInfo {
 	AttributedText description;
 
 	/// When the manga was last touched on the source (a new chapter, an edit).
-	/// @ref aniparse::unknown_time = the source does not state it. Sources differ on what
+	/// @c nullopt = the source does not state it. Sources differ on what
 	/// counts as an update, so this orders items within one source only.
-	std::chrono::system_clock::time_point update_time  = unknown_time;
-	/// When the manga was first published. @ref aniparse::unknown_time = the source does not
+	std::optional<ModelDate> update_time;
+	/// When the manga was first published. @c nullopt = the source does not
 	/// state it — common when only a year is known.
-	std::chrono::system_clock::time_point release_time = unknown_time;
+	std::optional<ModelDate> release_time;
 	/// Publication state (ongoing / released / announced / source-specific). A
 	/// default-constructed status (empty name) = the source states none, and reads as
 	/// DefaultAiredStatuses::Other rather than as "released". @see AiredStatus
@@ -204,7 +204,7 @@ struct MangaInfo {
 
 	/// How many pages the work has, when the source states it up front — meaningful for
 	/// one-shots and galleries (a booru pool, a doujin) whose whole length is one number.
-	/// nullopt = the source does not report it. Distinct from @ref total_chapters: a work
+	/// nullopt = the source does not report it. Distinct from @ref aniparse::MangaInfo::total_chapters — a work
 	/// is a count of chapters OR, when it has none, a count of pages.
 	std::optional<long> total_pages;
 
@@ -286,12 +286,12 @@ struct MangaChapterInfo {
 	/// none. Fetch descriptors, not the chapter's pages — those come from
 	/// chapter_pages(). @see Image
 	std::vector<Image> previews;
-	/// When the chapter was last edited/re-uploaded on the source; @ref aniparse::unknown_time
+	/// When the chapter was last edited/re-uploaded on the source; @c nullopt
 	/// = not stated.
-	std::chrono::system_clock::time_point update_time  = unknown_time;
-	/// When the chapter was published on the source; @ref aniparse::unknown_time = not stated.
+	std::optional<ModelDate> update_time;
+	/// When the chapter was published on the source; @c nullopt = not stated.
 	/// This is the source's posting date, not the original serialization date.
-	std::chrono::system_clock::time_point release_time = unknown_time;
+	std::optional<ModelDate> release_time;
 
 	/**
 	 * @brief Identity for the chapter_pages() round-trip

include/aniparse/types/Authentication.hpp

@@ -92,8 +92,8 @@ void import_auth(ParserConfig& config, const AuthState& state);
 
 /**
  * @brief How a source expects a user to sign in — the shape the client collects.
- * Declared by @ref Parser::auth_info so the client picks the right
- * @ref AuthenticationData variant and UI instead of guessing.
+ * Declared by @ref aniparse::Parser::auth_info so the client picks the right
+ * @ref aniparse::AuthenticationData variant and UI instead of guessing.
  */
 enum class AuthMethod {
 	/// A username + password fed to Parser::authenticate_context, which logs in and
@@ -115,7 +115,7 @@ enum class AuthMethod {
  * Describes a directly-injected credential — a token, an API key, a session
  * cookie — not the username/password fed to an interactive login (those drive a
  * handshake, they are not injected). @ref auth_keys_from_fields turns a list of
- * these into the @ref AuthKeys a session persists by, so a parser declares its
+ * these into the @ref aniparse::AuthKeys a session persists by, so a parser declares its
  * credential shape once.
  */
 struct AuthField {
@@ -172,7 +172,7 @@ struct AuthInfo {
 };
 
 /**
- * @brief Derive the persistable @ref AuthKeys from a credential-field list by
+ * @brief Derive the persistable @ref aniparse::AuthKeys from a credential-field list by
  * grouping each field's target under its channel. Lets a parser declare its
  * credential shape once (in AuthInfo::fields) and get auth_keys() for free.
  */

include/aniparse/types/Model.hpp

@@ -12,6 +12,7 @@
 #include <span>
 #include <array>
 #include <chrono>
+#include <cstdint>
 #include <optional>
 #include <string>
 #include <string_view>
@@ -25,7 +26,7 @@
  * These types are shared deliberately — a tag means the same thing whether it hangs
  * off a manga, an anime or an image container, so a consumer learns them once. Two
  * conventions run through the file and are worth reading before the individual
- * fields: an absent value (an empty string, a nullopt, @ref aniparse::unknown_time)
+ * fields: an absent value (an empty string, a @c nullopt @ref aniparse::ModelDate)
  * always means "the source did not state it", never "the item does not have it"; and
  * anything named @c ref is an opaque parser-owned handle, to be stored and passed
  * back, never parsed.
@@ -305,6 +306,38 @@ inline constexpr std::string_view aired_status_ongoing   = "ongoing";
 /// Canonical @ref AiredStatus::name for @ref aniparse::DefaultAiredStatuses::Announced.
 inline constexpr std::string_view aired_status_announced = "announced";
 
+/**
+ * @brief How precisely a source dated something — the granularity of a @ref aniparse::ModelDate.
+ *
+ * A source may give a full calendar day, or only a coarser bucket: a month, a quarter
+ * (an anime "season" — Winter/Spring/Summer/Fall map onto Q1..Q4), or a bare year. The
+ * date's @ref aniparse::ModelDate::time is pinned to the FIRST instant of that bucket (a year →
+ * Jan 1, Q3 → Jul 1), so ordering still works; this field says how much of it is real,
+ * so a consumer renders "2025" / "Q1 2025" / "March 2025" / the full date instead of a
+ * fabricated January 1.
+ */
+enum class DatePrecision : std::uint8_t {
+	Day,     ///< A full calendar day is known (the default). Render the whole date.
+	Month,   ///< Only the month is known — render e.g. "March 2025".
+	Quarter, ///< Only the quarter / anime season — @ref aniparse::ModelDate::time is its first day.
+	Year,    ///< Only the year is known — render e.g. "2025".
+};
+
+/**
+ * @brief A moment a source attaches to an item, carrying how precisely it is known.
+ *
+ * Wrapped rather than a bare time_point so the precision cannot drift from the value.
+ * A date field is @c std::optional<ModelDate>: @c nullopt means the source gave no date
+ * at all — an absent date is absent, not a sentinel epoch — and a present value is
+ * always a real moment plus its @ref aniparse::DatePrecision.
+ */
+struct ModelDate {
+	/// The instant, pinned to the first moment of the precision bucket (@ref aniparse::DatePrecision).
+	std::chrono::system_clock::time_point time;
+	/// How much of @ref aniparse::ModelDate::time the source actually stated.
+	DatePrecision precision = DatePrecision::Day;
+};
+
 /**
  * @brief Where an item stands in its publication/airing life: released, ongoing,
  * announced, or something only that source names.
@@ -322,11 +355,11 @@ struct AiredStatus {
 	/// status; that reads as @ref aniparse::DefaultAiredStatuses::Other, so an item whose
 	/// status is unknown is not silently reported as released.
 	std::string name;
-	/// The moment the source attaches to that state, when it gives one. Equal to
-	/// @ref aniparse::unknown_time (the default) when the source states only the state and no
-	/// date — the common case, so treat a date here as a bonus and never as a
-	/// reliable ordering key. Not to be confused with the item's own release_time.
-	std::chrono::system_clock::time_point time;
+	/// The moment the source attaches to that state, when it gives one. @c nullopt (the
+	/// default) when the source states only the state and no date — the common case, so
+	/// treat a date here as a bonus and never as a reliable ordering key. Not to be
+	/// confused with the item's own release_time.
+	std::optional<ModelDate> time;
 
 	/**
 	 * @brief Classify @ref name into the well-known set.
@@ -337,14 +370,6 @@ struct AiredStatus {
 	DefaultAiredStatuses to_enum() const;
 };
 
-/**
- * The value every time_point in the model carries when the source states no time:
- * the system_clock epoch, not a real timestamp. Every unset date field (an item's
- * release_time, a chapter's update_time, @ref aniparse::AiredStatus::time) compares equal to
- * this, so "unknown" is testable rather than merely early. A consumer must check for
- * it before formatting a date, or it will show 1970.
- */
-inline constexpr std::chrono::system_clock::time_point unknown_time{std::chrono::system_clock::duration{0}};
 
 /**
  * Structure representing rating (score) of the item (release, manga, etc.)
@@ -526,9 +551,9 @@ struct Comment {
 	RelatedUser author;
 	/// The body, with any links the source marked up preserved as attributes.
 	AttributedText text;
-	/// When it was posted; @ref aniparse::unknown_time when the source does not date it
+	/// When it was posted; @c nullopt when the source does not date it
 	/// (some report only a relative "2 days ago" the parser will not guess from).
-	std::chrono::system_clock::time_point time = unknown_time;
+	std::optional<ModelDate> time;
 	/// Net score / likes, if the source exposes one. Source-defined and possibly
 	/// negative where downvotes exist. nullopt = the source has no voting on
 	/// comments, or does not report it — never "zero votes".

include/aniparse/types/Search.hpp

@@ -292,7 +292,7 @@ inline constexpr std::string_view episodes        = pages;
 /// Filter by Tag. TextQuery for free-text sources; ItemSelection where the
 /// source enumerates its tags, keyed by the opaque token that equals Tag::ref
 /// so a tag from MangaInfo searches directly. @see ItemSelection
-/// The default @ref Tag::axis: a Tag with an empty axis filters through this key.
+/// The default @ref aniparse::Tag::axis — a Tag with an empty axis filters through this key.
 inline constexpr std::string_view tag             = "tag";
 /// Filter by genre — the coarse editorial category axis a source keeps SEPARATE
 /// from its finer tag axis (a source with one flat tag list uses @ref tag alone
@@ -322,7 +322,7 @@ inline constexpr std::string_view age_restriction = "age_res";
 // for search and autocomplete. A source uses whichever apply. @see suggest
 //
 // These keys — together with @ref tag and @ref genre above — are the vocabulary of
-// @ref Tag::axis. A Tag carries the key of the axis it belongs to; the pair
+// @ref aniparse::Tag::axis. A Tag carries the key of the axis it belongs to; the pair
 // (Tag::axis, Tag::ref) then names one option in the supported_filters group keyed by
 // that axis, so a tag read off an item routes straight back into the right filter and
 // a consumer may section its tag display by axis. An empty Tag::axis means @ref tag.

include/aniparse/utility/Time.hpp

@@ -30,10 +30,10 @@ namespace aniparse {
  *  - a zone: 'Z', "+03:00", "+0300", or none, in which case UTC is assumed.
  *
  * @param text The timestamp, with no surrounding whitespace.
- * @return The instant, or nullopt if @p text is not a timestamp. Note that nullopt is
- *         NOT @ref aniparse::unknown_time — a caller that models "unknown" as the epoch maps it
- *         over itself, so that a source sending "1970-01-01" is not mistaken for a
- *         source sending nothing.
+ * @return The instant, or nullopt if @p text is not a timestamp. Parsing assigns no
+ *         "unknown" meaning to any value: "1970-01-01" parses to a real epoch instant, so
+ *         a caller must distinguish it from an absent date (a @c nullopt @ref aniparse::ModelDate),
+ *         never from the timestamp itself.
  */
 [[nodiscard]] std::optional<std::chrono::system_clock::time_point> parse_iso8601(
     std::string_view text) noexcept;

include/aniparse/utility/UrlEncode.hpp

@@ -46,7 +46,7 @@ inline std::string url_encode(std::string_view value) {
 }
 
 /**
- * @brief Percent-decode a string per RFC 3986 — the inverse of @ref url_encode.
+ * @brief Percent-decode a string per RFC 3986 — the inverse of @ref aniparse::url_encode.
  * Each "%XX" (two hex digits) becomes the byte it names; a malformed or truncated
  * escape is left verbatim. '+' is passed through unchanged: it is a literal here,
  * NOT a space — this decodes a path or opaque segment, not an

tests/TimeTest.cpp

@@ -80,9 +80,9 @@ TEST_CASE("parse_iso8601 rejects what is not a timestamp") {
 }
 
 TEST_CASE("parse_iso8601 does not confuse absent with the epoch") {
-	// unknown_time is the epoch, so a source that genuinely sends 1970 must not be read
-	// as a source that sent nothing. That distinction is the caller's to make, which it
-	// can only do if the parser hands back an empty optional rather than a zero.
+	// A source that genuinely sends 1970 must not be read as a source that sent nothing.
+	// That distinction is the caller's to make, which it can only do if the parser hands
+	// back an empty optional rather than a zero (an absent date is a nullopt ModelDate).
 	const auto epoch = parse_iso8601("1970-01-01T00:00:00Z");
 	REQUIRE(epoch.has_value());
 	CHECK(*epoch == system_clock::time_point{});