From ad00cf38e5e81cda0898eec04ec47207bb7a9bf3 Mon Sep 17 00:00:00 2001
From: Andrea Fernandez Buitrago <15234535+anferbui@users.noreply.github.com>
Date: Wed, 19 Jun 2024 15:01:26 +0100
Subject: [PATCH] Adds documentation for new `@Available` behavior

Documents the format which is expected for the "introduced" field of the `@Available` directive.
---
 .../SwiftDocC/Semantics/Metadata/Availability.swift    | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/Sources/SwiftDocC/Semantics/Metadata/Availability.swift b/Sources/SwiftDocC/Semantics/Metadata/Availability.swift
index 9189d6fa77..726b51214b 100644
--- a/Sources/SwiftDocC/Semantics/Metadata/Availability.swift
+++ b/Sources/SwiftDocC/Semantics/Metadata/Availability.swift
@@ -32,6 +32,16 @@ extension Metadata {
     /// @Available("My Package", introduced: "1.0")
     /// ```
     ///
+    /// Only strings which are valid semantic version numbers may be passed to the second argument. Specifying an incomplete version number is allowed, as long as all components of the version are valid numbers:
+    ///
+    /// ```markdown
+    /// @Available("My Package", introduced: "1.0.0")
+    /// @Available("My Package", introduced: "1.0")
+    /// @Available("My Package", introduced: "1")
+    /// ```
+    ///
+    /// If an invalid semantic version number is provided, a compiler warning will be issued and the directive will be ignored.
+    ///
     /// This directive is available on both articles and documentation extension files. In extension
     /// files, the information overrides any information from the symbol itself.
     ///