Fix expand-availability syntax not to interfere with doc comment parsing

This was our previous convention:

    /// Fiddle with the thing.
    /*System 0.0.2*/
    public func foo()

    /// Fiddle with the thing.
    /*System 0.0.2, @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)*/
    public func foo()

    /// Fiddle with the thing.
    /*System 0.0.2*/@available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)
    public func foo()

Unfortunately, regular comments in between a declaration and its
preceding doc comments interfere with documentation tools.

Change things to the style below instead:

    /// Fiddle with the thing.
    @available(/*System 0.0.2*/macOS 10, *)
    public func foo()

    /// Fiddle with the thing.
    @available(/*SwiftSystem 0.0.2: macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0*/macOS 10, *)
    public func foo()

    /// Fiddle with the thing.
    @available(/*SwiftSystem 0.0.2*/macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)
    public func foo()

Unfortunately, `@available(*)` isn’t valid syntax, so we have to
add a dummy “macOS 10” version spec. It should have no actual effect.

Author: lorentey

Utilities/expand-availability.py

@@ -6,11 +6,18 @@
 # In order for this to work, ABI-impacting declarations need to be annotated
 # with special comments in the following format:
 #
-#     /*System 0.0.2*/
+#     @available(/*System 0.0.2*/iOS 8, *)
 #     public func greeting() -> String {
 #       "Hello"
 #     }
 #
+# (The iOS 8 availability is a dummy no-op declaration -- it only has to be there because
+# `@available(*)` isn't valid syntax, and commenting out the entire `@available` attribute
+# would interfere with parser tools for doc comments. `iOS 8` is the shortest version string that
+# matches the minimum possible deployment target for Swift code, so we use that as our dummy
+# availability version. `@available(iOS 8, *)` is functionally equivalent to not having an
+# `@available` attribute at all.)
+#
 # The script adds full availability incantations to these comments. It can run
 # in one of two modes:
 #
@@ -19,16 +26,16 @@
 # availability across `SystemPackage` and the ABI-stable `System` module that
 # ships in Apple's OS releases:
 #
-#     /*System 0.0.2, @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)*/
+#     @available(/*System 0.0.2: macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0*/iOS 8, *)
 #     public func greeting() -> String {
 #       "Hello"
 #     }
 #
-# `expand-availability.py --attributes` adds actual availability attributes.
+# `expand-availability.py --attributes` adds actual availability declarations.
 # This is used by maintainers to build ABI stable releases of System on Apple's
 # platforms:
 #
-#     /*System 0.0.2*/@available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)
+#     @available(/*System 0.0.2: */macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)
 #     public func greeting() -> String {
 #       "Hello"
 #     }
@@ -65,22 +72,44 @@ def swift_sources_in(path):
                 result.append(os.path.join(dir, file))
     return result
 
-macro_pattern = re.compile(
+# Old-style syntax:
+# /*System 0.0.2*/
+# /*System 0.0.2, @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)*/
+# /*System 0.0.2*/@available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)
+old_macro_pattern = re.compile(
     r"/\*(System [^ *]+)(, @available\([^)]*\))?\*/(@available\([^)]*\))?")
 
+# New-style comments:
+# @available(/*SwiftSystem 0.0.2*/macOS 10, *)
+# @available(/*SwiftSystem 0.0.2: macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0*/iOS 8, *)
+# @available(/*SwiftSystem 0.0.2*/macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)
+#
+# These do not interfere with our tools' ability to find doc comments.
+macro_pattern = re.compile(
+    r"@available\(/\*(System [^ *:]+)[^*/)]*\*/([^)]*)\*\)")
+
+def available_attribute(filename, lineno, symbolic_version):
+    expansion = versions[symbolic_version]
+    if expansion is None:
+        raise ValueError("{0}:{1}: error: Unknown System version '{0}'"
+            .format(fileinput.filename(), fileinput.lineno(), symbolic_version))
+    if args.attributes:
+        attribute = "@available(/*{0}*/{1}, *)".format(symbolic_version, expansion)
+    else:
+        # Sadly `@available(*)` is not valid syntax, so we have to mention at least one actual
+        # platform here.
+        attribute = "@available(/*{0}: {1}*/iOS 8, *)".format(symbolic_version, expansion)
+    return attribute
+
+
 sources = swift_sources_in("Sources") + swift_sources_in("Tests")
 for line in fileinput.input(files=sources, inplace=True):
     match = re.search(macro_pattern, line)
+    if match is None:
+        match = re.search(old_macro_pattern, line)
     if match:
-        system_version = match.group(1)
-        expansion = versions[system_version]
-        if expansion is None:
-            raise ValueError("{0}:{1}: error: Unknown System version '{0}'"
-                             .format(fileinput.filename(), fileinput.lineno(),
-                                     system_version))
-        if args.attributes:
-            replacement = "/*{0}*/@available({1}, *)".format(system_version, expansion)
-        else:
-            replacement = "/*{0}, @available({1}, *)*/".format(system_version, expansion)
+        symbolic_version = match.group(1)
+        replacement = available_attribute(
+            fileinput.filename(), fileinput.lineno(), symbolic_version)
         line = line[:match.start()] + replacement + line[match.end():]
     print(line, end="")