Add more documentation about the @Image source value (#1167)

* Add more documentation about the @image source value

Also, add some information from the images article to the @image directive documentation.

* Consistently omit quotation marks and file extensions in `@Image` examples

* Use a multiplication sign instead of the letter "x" in prose to refer to the 2 times scaled display mode

* Apply suggestions from code review

Co-authored-by: Andrea Fernandez Buitrago <[email protected]>

---------

Co-authored-by: Andrea Fernandez Buitrago <[email protected]>

Author: d-ronnqvist

Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/Shared Directives/Chapter/Chapter.md

@@ -23,7 +23,7 @@ Use `Chapter` directives to organize related tutorial pages into groupings. For
     ...
     
     @Chapter(name: "SlothCreator Essentials") {
-        @Image(source: "chapter1-slothcreatorEssentials.png", alt: "A wireframe of an app interface that has an outline of a sloth and four buttons below the sloth. The buttons display the following symbols, from left to right: snowflake, fire, wind, and lightning.")
+        @Image(source: chapter1-slothcreatorEssentials, alt: "A wireframe of an app interface that has an outline of a sloth and four buttons below the sloth. The buttons display the following symbols, from left to right: snowflake, fire, wind, and lightning.")
         
         Create custom sloths and edit their attributes and powers using SlothCreator.
         

Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/Shared Directives/Image.md

@@ -7,33 +7,48 @@ Displays an image in a tutorial.
 }
 
 - Parameters:
-    - source: The name and file extension of an image in your Swift framework or package project. **(required)**
+    - source: The name of an image in your documentation catalog ('.docc' directory). **(required)**
+
+      Omit the appearance (for example `~dark`) and display scale (for example `@2x`) components. 
+      The file extension component (for example `.png`) is optional and can be omitted.
+      For more information about the components of an image filename, see <doc:adding-images>.
+
+      If the image name contains either whitespace characters, commas (`,`), or colons (`:`) you need to surround it with quotation marks (`"`).  
     - alt: Alternative text that describes the image to screen readers. **(required)**
 
 ## Overview
 
 The `Image` directive displays an image in your tutorial. Provide the name of an image and alternative text that describes the image in sufficient detail so screen readers can read that text aloud for people who are blind or have low-vision.
 
 ```
-@Image(source: "overview-hero.png", alt: "An illustration of a sleeping sloth, hanging from a tree branch.”)
+@Image(source: overview-hero, alt: "An illustration of a sleeping sloth, hanging from a tree branch.”)
 ````
 
-Images can exist anywhere in your code base, but it's good practice to centralize them in a resources folder. You create this folder in your documentation catalog. Within your code base, image names must be unique. Images must be in *.png*, *.jpg*, *.jpeg*, *.svg*, or *.gif* format.
+Images can exist anywhere in your documentation catalog ('.docc' directory). but it's good practice to use subdirectories to organize the content and assets in your documentation.
+Regardless of organization within your catalog, each image needs to have a unique name. 
+
+The supported image file extensions are `png`, `jpg`, `jpeg`, `svg` and `gif`.
 
-- Tip: To differentiate tutorial images from reference documentation images, you may wish to prefix image file names with tutorial\.
+- Tip: To differentiate tutorial images from reference documentation images, you may wish to prefix image file names with "tutorial".
 
 ### Provide Image Variants
 
-To ensure images render well on both standard and high-resolution displays, and in light and dark appearance modes, you can provide up to four versions of each image.
+To ensure that images render well on both standard and high-resolution displays, and in light and dark appearance modes, 
+you can provide appearance and display scale-aware versions of each image by including specific components in the image filename.
+
+![An image of a filename that's split into four labeled sections to highlight the individual components. From left to right, the components are the image name, the appearance mode, the display scale, and the file extension.](docc-image-filename)
+
+For example, the following are all valid DocC image filenames:
 
-Use the following naming conventions for your image files:
+- term `sloth.png`: An image that's independent of all appearance modes and display scales.
+- term `sloth~dark.png`: An image that's specific to dark mode, but is display-scale independent.
+- term `[email protected]`: An image that's specific to dark mode and the 2× display scale.
 
-- term Standard Light: *[filename].[extension]*, e.g. *filename.png*
-- term High-Resolution Light: *[filename]@2x.[extension]*, e.g. *[email protected]*
-- term Standard Dark: *[filename]~dark.[extension]*, e.g. *filename~dark.png*
-- term High-Resolution Dark: *[filename]~dark@2x.[extension]*, e.g. *[email protected]*
+Omit the appearance and display scale components when specifying an image name for the `source` parameter. 
+For example, if you write `@Image(source: overview-hero, alt: " ... ")` and the reader views that tutorial page **on a display that has dark appearance mode** enabled, the system displays *[email protected]*. 
 
-Exclude the resolution and appearance-variant suffixes when specifying an image name in the `source` parameter. For example, when you specify `@Image(source: "overview-hero.png", alt: " ... ")`, the appropriate variant automatically displays based on the reader's context. If the reader views the tutorial **on a display that has dark appearance mode** enabled, *[email protected]* is shown. At minimum, strive to provide high resolution variants **in light and dark appearance modes.** If you don't provide a certain variant, **the system displays the closest match.**
+At minimum, strive to provide high resolution variants **in light and dark appearance modes.** 
+If you don't provide a variant that matches the readers context, the system displays the closest matching image variant.
 
 ### Containing Elements
 
@@ -47,4 +62,4 @@ The following tutorial elements can include images.
 * ``Tutorial``
 * ``Volume``
 
-<!-- Copyright (c) 2021 Apple Inc and the Swift Project authors. All Rights Reserved. -->
+<!-- Copyright (c) 2021-2025 Apple Inc and the Swift Project authors. All Rights Reserved. -->

Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/Top-Level Directives/Tutorial/Section/Steps/Step/Code.md

@@ -45,15 +45,15 @@ Add an ``Image`` directive to show a preview of what the reader sees after perfo
                 Add the `sloth` parameter to initialize the `CustomizedSlothView` in the preview provider, and pass a new `Sloth` instance for the value.
                 
                 @Code(name: "CustomizedSlothView.swift", file: "01-creating-code-02-07.swift") {
-                    @Image(source: "preview-01-creating-code-02-07.png", alt: "A portrait of a generic sloth displayed in the center of the canvas.")
+                    @Image(source: preview-01-creating-code-02-07, alt: "A portrait of a generic sloth displayed in the center of the canvas.")
                 }
             }
 
             @Step {
                 Set the preview provider sloth's `name` to `"Super Sloth"`, `color` to `.blue`, and `power` to `.ice`.
                 
                 @Code(name: "CustomizedSlothView.swift", file: "01-creating-code-02-08.swift") {
-                    @Image(source: "preview-01-creating-code-02-08.png", alt: "A portrait of an ice sloth on top, followed by four power icons below. The power icons, clockwise from top left, include: ice, fire, wind, and lightning. The ice icon is selected.")
+                    @Image(source: preview-01-creating-code-02-08, alt: "A portrait of an ice sloth on top, followed by four power icons below. The power icons, clockwise from top left, include: ice, fire, wind, and lightning. The ice icon is selected.")
                 }    
             
                 ...
@@ -85,4 +85,4 @@ The following items can include a code element:
 
 - ``Image``
 
-<!-- Copyright (c) 2021 Apple Inc and the Swift Project authors. All Rights Reserved. -->
+<!-- Copyright (c) 2021-2025 Apple Inc and the Swift Project authors. All Rights Reserved. -->

Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/Top-Level Directives/Tutorial/Section/Steps/Step/Step.md

@@ -30,7 +30,7 @@ Use the `Step` directive to define a single task the reader performs within a se
                 @Step {
                     Create the folder.
                     
-                    @Image(source: "placeholder-image.png", alt: "A screenshot using the `mkdir` command to create a folder to place SlothCreator in.")
+                    @Image(source: placeholder-image, alt: "A screenshot using the `mkdir` command to create a folder to place SlothCreator in.")
                 }
                 
                 ...
@@ -82,4 +82,4 @@ The following items can include a step:
 - ``Image``
 - ``Video``
 
-<!-- Copyright (c) 2021 Apple Inc and the Swift Project authors. All Rights Reserved. -->
+<!-- Copyright (c) 2021-2025 Apple Inc and the Swift Project authors. All Rights Reserved. -->

Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/Top-Level Directives/Tutorial/Tutorial.md

@@ -89,7 +89,7 @@ A tutorial page begins with an introduction section, defined by an ``Intro`` dir
     @Intro(title: "Creating and Building a Swift Package") {
         This tutorial guides you through creating and building a Swift Package. Use the package to add your own re-usable classes and structures.
         
-        @Image(source: "creating-intro.png", alt: "An image of the Swift logo.")
+        @Image(source: creating-intro, alt: "An image of the Swift logo.")
     }
 
     ...
@@ -122,13 +122,13 @@ Define sections using the ``Section`` directive. You can optionally start with d
             @Step {
                 Create the directory.
                 
-                @Image(source: "placeholder-image.png", alt: "A screenshot showing the command to type in the terminal to create the directory.")
+                @Image(source: placeholder-image, alt: "A screenshot showing the command to type in the terminal to create the directory.")
             }
             
             @Step {
                 Create the Swift Package. 
                 
-                @Image(source: "placeholder-image.png", alt: "A screenshot showing the command to type in the terminal to create the Swift package.")
+                @Image(source: placeholder-image, alt: "A screenshot showing the command to type in the terminal to create the Swift package.")
             }
             
             @Step {
@@ -256,4 +256,4 @@ A tutorial page can contain the following items:
 
 - <doc:building-an-interactive-tutorial>
 
-<!-- Copyright (c) 2021 Apple Inc and the Swift Project authors. All Rights Reserved. -->
+<!-- Copyright (c) 2021-2025 Apple Inc and the Swift Project authors. All Rights Reserved. -->

Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/Top-Level Directives/Tutorials/Tutorials.md

@@ -21,11 +21,11 @@ Use a text editor to add a tutorial table of contents file to your documentation
         Create, catalog, and care for sloths using SlothCreator. 
         Get started with SlothCreator by building the demo app _Slothy_.
         
-        @Image(source: "slothcreator-intro.png", alt: "An illustration of 3 iPhones in portrait mode, displaying the UI of finding, creating, and taking care of a sloth in Slothy — the sample app that you build in this collection of tutorials.")
+        @Image(source: slothcreator-intro, alt: "An illustration of 3 iPhones in portrait mode, displaying the UI of finding, creating, and taking care of a sloth in Slothy — the sample app that you build in this collection of tutorials.")
     }
     
     @Chapter(name: "SlothCreator Essentials") {
-        @Image(source: "chapter1-slothcreatorEssentials.png", alt: "A wireframe of an app interface that has an outline of a sloth and four buttons below the sloth. The buttons display the following symbols, from left to right: snowflake, fire, wind, and lightning.")
+        @Image(source: chapter1-slothcreatorEssentials, alt: "A wireframe of an app interface that has an outline of a sloth and four buttons below the sloth. The buttons display the following symbols, from left to right: snowflake, fire, wind, and lightning.")
         
         Create custom sloths and edit their attributes and powers using SlothCreator.
         

Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/building-an-interactive-tutorial.md

@@ -33,13 +33,13 @@ Use a text editor and the following listing to create a table of contents file n
     @Intro(title: "Add a title for your introduction here.") {
         Add engaging introduction text here.
         
-        @Image(source: "toc-introduction-image-filename.png", alt: "Add an accessible description for your image here.")
+        @Image(source: toc-introduction-image-filename, alt: "Add an accessible description for your image here.")
     }
     
     @Chapter(name: "Add a chapter title here.") {
         Add chapter text here.
         
-        @Image(source: "chapter-image-filename-here.png", alt: "Add an accessible description for your image here.")
+        @Image(source: chapter-image-filename-here, alt: "Add an accessible description for your image here.")
         
         @TutorialReference(tutorial: "doc:tutorial-page-file-name-here")
         @TutorialReference(tutorial: "doc:another-tutorial-page-file-name-here")
@@ -65,21 +65,21 @@ Tutorial pages provide instructions that walk through using your APIs in realist
     @Intro(title: "Add the name of your title here.") {
         Add engaging introduction text here.
 
-        @Image(source: "intro-image-filename-here.jpg", alt: "Add an accessible description for your image here.")
+        @Image(source: intro-image-filename-here, alt: "Add an accessible description for your image here.")
     }
 
     @Section(title: "Add the name of your section here.") {
         @ContentAndMedia {
             Add engaging section text here.
 
-            @Image(source: "section-image-filename-here.jpg", alt: "Add an accessible description for your image here.")    
+            @Image(source: section-image-filename-here, alt: "Add an accessible description for your image here.")    
         }
 
         @Steps {
             @Step {
                 Add engaging step 1 text here.
 
-                @Image(source: "step-1-image-filename-here.jpg", alt: "Add an accessible description for your step here.")
+                @Image(source: step-1-image-filename-here, alt: "Add an accessible description for your step here.")
             }
             
             @Step {
@@ -99,24 +99,24 @@ Replace the placeholders with your custom content. Use the ``Intro`` directive t
     @Intro(title: "Add a title for your tutorial page here.") {
         Add engaging introduction text here.
 
-        @Image(source: "tutorial-introduction-image-filename.png", alt: "Add an accessible description for your image here.")
+        @Image(source: tutorial-introduction-image-filename, alt: "Add an accessible description for your image here.")
     }
 
     @Section(title: "Add a section title here") {
         @ContentAndMedia {
             Add some content here to introduce the steps that follow.
 
-            @Image(source: "section-image-filename.png", alt: "Add an accessible description for your image here.")
+            @Image(source: section-image-filename, alt: "Add an accessible description for your image here.")
         }
 
         @Steps {
             @Step {
                 Provide text for a step here.
-                @Image(source: "step1-image-filename.png", alt: "Add an accessible description for your image here.")
+                @Image(source: step1-image-filename, alt: "Add an accessible description for your image here.")
             }
             @Step {
                 Provide text for another step here.
-                @Image(source: "step2-image-filename.png", alt: "Add an accessible description for your image here.")
+                @Image(source: step2-image-filename, alt: "Add an accessible description for your image here.")
             }
         }
     }
@@ -176,4 +176,4 @@ DocC compiles your documentation catalog and generates the tutorial. Copy the UR
 
 Learn how to share your documentation in <doc:distributing-documentation-to-other-developers>.
 
-<!-- Copyright (c) 2021 Apple Inc and the Swift Project authors. All Rights Reserved. -->
+<!-- Copyright (c) 2021-2025 Apple Inc and the Swift Project authors. All Rights Reserved. -->

Sources/docc/DocCDocumentation.docc/adding-images.md

@@ -22,7 +22,7 @@ For example, the following are all valid DocC image filenames:
 
 - term `sloth.png`: An image that's independent of all appearance modes and display scales.
 - term `sloth~dark.png`: An image that's specific to dark mode, but is display-scale independent.
-- term `[email protected]`: An image that's specific to dark mode and the 2x display scale.
+- term `[email protected]`: An image that's specific to dark mode and the 2× display scale.
 
 > Important: Include the image files in your documentation catalog. For more information, see <doc:documenting-a-swift-framework-or-package>.
 
@@ -39,4 +39,4 @@ image.
 ![A sloth hanging off a tree.](sloth)
 ```
 
-<!-- Copyright (c) 2023 Apple Inc and the Swift Project authors. All Rights Reserved. -->
+<!-- Copyright (c) 2023-2025 Apple Inc and the Swift Project authors. All Rights Reserved. -->