From d5aea7f980cdac869114f0fd0535739b10c0c4a1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Thu, 19 Dec 2024 16:31:11 +0100
Subject: [PATCH] Add illustrations of how DocC displays language specific
 parameter and return value documentation.

Also, rephrase note as tip
---
 ...with-different-language-representations.md | 46 +++++++++++++++----
 .../params-1-objc.svg                         | 28 +++++++++++
 .../params-1-objc~dark.svg                    | 27 +++++++++++
 .../params-1-swift.svg                        | 24 ++++++++++
 .../params-1-swift~dark.svg                   | 22 +++++++++
 .../params-2-objc.svg                         | 44 ++++++++++++++++++
 .../params-2-objc~dark.svg                    | 40 ++++++++++++++++
 .../params-2-swift.svg                        | 17 +++++++
 .../params-2-swift~dark.svg                   | 15 ++++++
 .../params-3-objc.svg                         | 41 +++++++++++++++++
 .../params-3-objc~dark.svg                    | 40 ++++++++++++++++
 .../params-3-swift.svg                        | 21 +++++++++
 .../params-3-swift~dark.svg                   | 19 ++++++++
 13 files changed, 376 insertions(+), 8 deletions(-)
 rename Sources/docc/DocCDocumentation.docc/{ => Documenting API with different language representations}/documenting-api-with-different-language-representations.md (80%)
 create mode 100644 Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-1-objc.svg
 create mode 100644 Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-1-objc~dark.svg
 create mode 100644 Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-1-swift.svg
 create mode 100644 Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-1-swift~dark.svg
 create mode 100644 Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-2-objc.svg
 create mode 100644 Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-2-objc~dark.svg
 create mode 100644 Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-2-swift.svg
 create mode 100644 Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-2-swift~dark.svg
 create mode 100644 Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-3-objc.svg
 create mode 100644 Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-3-objc~dark.svg
 create mode 100644 Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-3-swift.svg
 create mode 100644 Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-3-swift~dark.svg

diff --git a/Sources/docc/DocCDocumentation.docc/documenting-api-with-different-language-representations.md b/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/documenting-api-with-different-language-representations.md
similarity index 80%
rename from Sources/docc/DocCDocumentation.docc/documenting-api-with-different-language-representations.md
rename to Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/documenting-api-with-different-language-representations.md
index ca3562329..5865ce3c8 100644
--- a/Sources/docc/DocCDocumentation.docc/documenting-api-with-different-language-representations.md
+++ b/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/documenting-api-with-different-language-representations.md	
@@ -52,11 +52,31 @@ func doSomething(with someValue: Int) throws
 
 Because the Swift representation of this method only has the "someValue" parameter and no return value, DocC hides the "error" parameter documentation and the return value documentation from the Swift version of this symbol's page.
 
+@Row {
+  @Column {
+    ![](params-1-swift)    
+  }
+  @Column {
+    ![](params-1-objc)
+  }    
+}
+
 You don't need to document the Objective-C representation's "error" parameter or the Objective-C specific return value for methods that correspond to throwing functions in Swift.
 DocC automatically adds a generic description for the "error" parameter for the Objective-C version of that symbol's page. 
+If you want to customize this documentation you can manually document the "error" parameter.
+Doing so won't change the Swift version of that symbol's page.
 
 When the Swift representation returns `Void`---which corresponds to a `BOOL` return value in Objective-C (like in the example above)---DocC adds a generic description of the `BOOL` return value to the Objective-C version of that symbol's page. 
 
+@Row {
+  @Column {
+    ![](params-2-swift)    
+  }
+  @Column {
+    ![](params-2-objc)
+  }    
+}
+
 When the Swift representation returns a value---which corresponds to a `nullable` return value in Objective-C---DocC extends your return value documentation, for the Objective-C version of that symbol's page, to describe that the methods returns `nil` if an error occurs unless your documentation already covers this behavior. 
 For example, consider this throwing function in Swift and its corresponding Objective-C interface:
 
@@ -65,7 +85,7 @@ For example, consider this throwing function in Swift and its corresponding Obje
 ```swift
 /// - Parameters:
 ///   - someValue: Some description of this parameter.
-/// - Returns: Some description of this return value.
+/// - Returns: Some general description of this return value.
 @objc func doSomething(with someValue: Int) throws -> String
 ```
 
@@ -81,14 +101,24 @@ DocC displays the "someValue" parameter documentation and return value documenta
 For the Objective-C representation, with two parameters and a nullable return value,
 DocC displays the "someValue" parameter documentation, generic "error" parameter documentation, and extends the return value documentation with a generic description about the Objective-C specific `nil` return value when the method encounters an error. 
 
-If you want to customize this documentation you can manually document the "error" parameter and return value.
-Doing so won't change the Swift version of that symbol's page.
-DocC will still hide the parameter and return value documentation that doesn't apply to each source language's version of that symbol's page.
+@Row {
+  @Column {
+    ![](params-3-swift)    
+  }
+  @Column {
+    ![](params-3-objc)
+  }    
+}
 
-If your return value documentation already describes the `nil` return value, DocC won't extent it with the generic `nil` value description.
+> Tip:
+> If you document the Objective-C specific `nil` return value for a method that corresponds to a throwing function in Swift,
+> but don't provide more information to the reader than "On failure, this method returns `nil`", 
+> consider removing that written documentation to let DocC display its generic description about the Objective-C specific `nil` return value, 
+> only on the Objective-C version of that symbol's page.
 
-> Note:
-> If you document the Objective-C specific `nil` return value for a method that correspond to a throwing function in Swift, 
-> DocC will display that documentation as-is on the Swift version of that page where is has a non-optional return type.
+The return value documentation you write displays on both the Swift and Objective-C versions of that symbol's page.
+DocC won't add its generic `nil` return value description to the Objective-C page, 
+if your return value documentation already describes that the method returns `nil` when it fails or encounters an error,
+but that Objective-C specific documentation you've written will display on the Swift version of that page where the symbol has a non-optional return type.
 
 <!-- Copyright (c) 2024 Apple Inc and the Swift Project authors. All Rights Reserved. -->
diff --git a/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-1-objc.svg b/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-1-objc.svg
new file mode 100644
index 000000000..42fd029a3
--- /dev/null
+++ b/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-1-objc.svg	
@@ -0,0 +1,28 @@
+<svg width="300" height="157" viewBox="0 0 300 157" xmlns="http://www.w3.org/2000/svg">
+  <style>
+    text { fill: black; }
+    text.heading { font-family: "HelveticaNeue", Helvetica, Arial, sans-serif; font-size: 15px; }
+    text.param { font-family: "Menlo", monospace; font-weight: bold; font-size: 8.5px; }
+    text.lang { fill: #0066ff; font-weight: 600; }
+    rect { height: 10px; rx: 2px; ry: 2px; fill: #e3e3e3; }
+    rect.code { fill: #d8d8d8; }
+    rect.del { fill: none; stroke: red; stroke-dasharray: 4px; }
+  </style>
+  <text class="heading lang" x="295" y="17.3" text-anchor="end">Objective-C</text>
+    
+  <text class="heading" x="5" y="17.3">Parameters</text>
+  <text class="param" x="13.5" y="35.92">someValue</text>
+  <rect x="22.5" y="41.92" width="142.37"/>
+  
+  <text class="param" x="13.5" y="69.67">error</text>
+  <rect x="22.5" y="75.17" width="261.73"/>
+  <rect x="22.5" y="88.42" width="84.85"/>
+  <rect class="code" x="108.35" y="88.42" width="12.55" />
+  <rect x="121.9" y="88.42" width="81.01"/>
+  
+  <text class="heading" x="5" y="132.6">Return Value</text>
+  <rect class="code" x="5.5" y="144.1" width="12.55"/>
+  <rect x="19.05" y="144.1" width="152.52"/>
+  <rect class="code" x="172.57" y="144.1" width="8.03"/>
+  <rect x="181.6" y="144.1" width="80.67"/>
+</svg>
diff --git a/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-1-objc~dark.svg b/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-1-objc~dark.svg
new file mode 100644
index 000000000..8015a5489
--- /dev/null
+++ b/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-1-objc~dark.svg	
@@ -0,0 +1,27 @@
+<svg width="300" height="157" viewBox="0 0 300 157" xmlns="http://www.w3.org/2000/svg">
+  <style>
+    text { fill: white; }
+    text.heading { font-family: "HelveticaNeue", Helvetica, Arial, sans-serif; font-size: 15px; }
+    text.param { font-family: "Menlo", monospace; font-weight: bold; font-size: 8.5px; }
+    text.lang { fill: #0066ff; font-weight: 600; }
+    rect { height: 10px; rx: 2px; ry: 2px; fill: #404040; }
+    rect.code { fill: #555555; }
+  </style>
+  <text class="heading lang" x="295" y="17.3" text-anchor="end">Objective-C</text>
+    
+  <text class="heading" x="5" y="17.3">Parameters</text>
+  <text class="param" x="13.5" y="35.92">someValue</text>
+  <rect x="22.5" y="41.92" width="142.37"/>
+  
+  <text class="param" x="13.5" y="69.67">error</text>
+  <rect x="22.5" y="75.17" width="261.73"/>
+  <rect x="22.5" y="88.42" width="84.85"/>
+  <rect class="code" x="108.35" y="88.42" width="12.55" />
+  <rect x="121.9" y="88.42" width="81.01"/>
+  
+  <text class="heading" x="5" y="132.6">Return Value</text>
+  <rect class="code" x="5.5" y="144.1" width="12.55"/>
+  <rect x="19.05" y="144.1" width="152.52"/>
+  <rect class="code" x="172.57" y="144.1" width="8.03"/>
+  <rect x="181.6" y="144.1" width="80.67"/>
+</svg>
diff --git a/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-1-swift.svg b/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-1-swift.svg
new file mode 100644
index 000000000..44ea8c24a
--- /dev/null
+++ b/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-1-swift.svg	
@@ -0,0 +1,24 @@
+<svg width="300" height="157" viewBox="0 0 300 157" xmlns="http://www.w3.org/2000/svg">
+  <style>
+    text { fill: black; }
+    text.heading { font-family: "HelveticaNeue", Helvetica, Arial, sans-serif; font-size: 15px; }
+    text.param { font-family: "Menlo", monospace; font-weight: bold; font-size: 8.5px; }
+    text.lang { fill: #0066ff; font-weight: 600; }
+    rect { height: 10px; rx: 2px; ry: 2px; fill: #e3e3e3; }
+    rect.code { fill: #d8d8d8; }
+    rect.del { fill: none; stroke: red; stroke-dasharray: 4px; height: 9.5px; }
+  </style>
+  
+  <text class="heading lang" x="295" y="17.3" text-anchor="end">Swift</text>
+    
+  <text class="heading" x="5" y="17.3">Parameters</text>
+  <text class="param" x="13.5" y="35.92">someValue</text>
+  <rect x="22.5" y="41.92" width="142.37"/>
+  
+  <rect class="del" x="13.5" y="63.4" width="25.3" style="height: 8px"/>
+  <rect class="del" x="22.5" y="75.17" width="261.73"/>
+  <rect class="del" x="22.5" y="88.42" width="180.75"/>
+  
+  <rect class="del" x="6.5" y="121.2" width="86.3" style="height: 13.5px"/>
+  <rect class="del" x="6.5" y="144.1" width="257.67"/>
+</svg>
diff --git a/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-1-swift~dark.svg b/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-1-swift~dark.svg
new file mode 100644
index 000000000..f7e1d94d3
--- /dev/null
+++ b/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-1-swift~dark.svg	
@@ -0,0 +1,22 @@
+<svg width="300" height="157" viewBox="0 0 300 157" xmlns="http://www.w3.org/2000/svg">
+  <style>
+    text { fill: white; }
+    text.heading { font-family: "HelveticaNeue", Helvetica, Arial, sans-serif; font-size: 15px; }
+    text.param { font-family: "Menlo", monospace; font-weight: bold; font-size: 8.5px; }
+    text.lang { fill: #0066ff; font-weight: 600; }
+    rect { height: 10px; rx: 2px; ry: 2px; fill: #404040; }
+    rect.del { fill: none; stroke: #bc0000; stroke-dasharray: 4px; height: 9.5px; }
+  </style>
+  <text class="heading lang" x="295" y="17.3" text-anchor="end">Swift</text>
+    
+  <text class="heading" x="5" y="17.3">Parameters</text>
+  <text class="param" x="13.5" y="35.92">someValue</text>
+  <rect x="22.5" y="41.92" width="142.37"/>
+  
+  <rect class="del" x="13.5" y="63.4" width="25.3" style="height: 8px"/>
+  <rect class="del" x="22.5" y="75.17" width="261.73"/>
+  <rect class="del" x="22.5" y="88.42" width="180.75"/>
+  
+  <rect class="del" x="6.5" y="121.2" width="86.3" style="height: 13.5px"/>
+  <rect class="del" x="6.5" y="144.1" width="257.67"/>
+</svg>
diff --git a/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-2-objc.svg b/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-2-objc.svg
new file mode 100644
index 000000000..e298319d2
--- /dev/null
+++ b/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-2-objc.svg	
@@ -0,0 +1,44 @@
+<svg width="300" height="169" viewBox="0 0 300 169" xmlns="http://www.w3.org/2000/svg">
+  <style>
+    text { fill: black; font-family: "HelveticaNeue", Helvetica, Arial, sans-serif; font-size: 9px; }
+    text.code { font-family: "Menlo", monospace; font-size: 8px; }
+    text.heading { font-size: 15px; }
+    text.param { font-family: "Menlo", monospace; font-weight: bold; font-size: 8.5px; }
+    text.lang { fill: #0066ff; font-weight: 600; }
+    rect { height: 10px; rx: 2px; ry: 2px; fill: #e3e3e3; }
+    rect.code { fill: #d8d8d8; }
+    rect.add { fill: rgba(0,180,60,0.2); height: 11px; }
+  </style>
+  
+  <text class="heading lang" x="295" y="17.3" text-anchor="end">Objective-C</text>
+    
+  <text class="heading" x="5" y="17.3">Parameters</text>
+  <text class="param" x="13.5" y="35.92">someValue</text>
+  <rect x="22.5" y="41.92" width="142.37"/>
+  
+  <rect class="add" x="12.5" y="62.7" width="27.7" style="height: 9px"/>
+  <rect class="add" x="20.2" y="76.17" width="250.23"/>
+  <rect class="add" x="20.2" y="89.42" width="268.75"/>
+  <rect class="add" x="20.2" y="102.17" width="211.23"/>
+ 
+  
+  <text class="param" x="13.5" y="69.67">error</text>
+  <text x="22" y="84.72">On output, a pointer to an error object that describes why the </text>
+  <text x="22" y="97.4">method failed, or </text>
+  <text class="code" x="92.69" y="97.4">nil</text>
+  <text x="109.73" y="97.4" > if no error occurred. If you are not interested </text>
+  <text x="22" y="110.65">in the error information, pass </text>
+  <text class="code" x="140.03" y="110.65">nil</text>
+  <text x="157.07" y="110.65"> for this parameter.</text>
+    
+  <rect class="add" x="4" y="130.2" width="88.3" style="height: 14.5px"/>
+  <rect class="add" x="4" y="155" width="180.17"/>
+    
+  <text class="heading" x="5" y="142.85">Return Value</text>
+  <text class="code" x="5" y="163.32">YES</text>
+  <text x="22.05" y="163.32"> if the method succeeded, otherwise </text>
+  <text class="code" x="169.58" y="163.32">NO</text>
+  <text x="179.61" y="163.32">.</text>
+  
+ 
+</svg>
diff --git a/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-2-objc~dark.svg b/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-2-objc~dark.svg
new file mode 100644
index 000000000..5d8e612aa
--- /dev/null
+++ b/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-2-objc~dark.svg	
@@ -0,0 +1,40 @@
+<svg width="300" height="169" viewBox="0 0 300 169" xmlns="http://www.w3.org/2000/svg">
+  <style>
+    text { fill: white; font-family: "HelveticaNeue", Helvetica, Arial, sans-serif; font-size: 9px; }
+    text.code { font-family: "Menlo", monospace; font-size: 8px; }
+    text.heading { font-size: 15px; }
+    text.param { font-family: "Menlo", monospace; font-weight: bold; font-size: 8.5px; }
+    text.lang { fill: #0066ff; font-weight: 600; }
+    rect { height: 10px; rx: 2px; ry: 2px; fill: #404040; }
+    rect.code { fill: #5a5a5a; }
+    rect.add { fill: rgba(30,255,30,0.33); height: 11px; }
+  </style>
+  <text class="heading lang" x="295" y="17.3" text-anchor="end">Objective-C</text>
+    
+  <text class="heading" x="5" y="17.3">Parameters</text>
+  <text class="param" x="13.5" y="35.92">someValue</text>
+  <rect x="22.5" y="41.92" width="142.37"/>
+  
+  <rect class="add" x="12.5" y="62.7" width="27.7" style="height: 9px"/>
+  <rect class="add" x="20.2" y="76.17" width="250.23"/>
+  <rect class="add" x="20.2" y="89.42" width="268.75"/>
+  <rect class="add" x="20.2" y="102.17" width="211.23"/>
+ 
+  <text class="param" x="13.5" y="69.67">error</text>
+  <text x="22" y="84.72">On output, a pointer to an error object that describes why the </text>
+  <text x="22" y="97.4">method failed, or </text>
+  <text class="code" x="92.69" y="97.4">nil</text>
+  <text x="109.73" y="97.4" > if no error occurred. If you are not interested </text>
+  <text x="22" y="110.65">in the error information, pass </text>
+  <text class="code" x="140.03" y="110.65">nil</text>
+  <text x="157.07" y="110.65"> for this parameter.</text>
+    
+  <rect class="add" x="4" y="130.2" width="88.3" style="height: 14.5px"/>
+  <rect class="add" x="4" y="155" width="180.17"/>
+    
+  <text class="heading" x="5" y="142.85">Return Value</text>
+  <text class="code" x="5" y="163.32">YES</text>
+  <text x="22.05" y="163.32"> if the method succeeded, otherwise </text>
+  <text class="code" x="169.58" y="163.32">NO</text>
+  <text x="179.61" y="163.32">.</text>
+</svg>
diff --git a/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-2-swift.svg b/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-2-swift.svg
new file mode 100644
index 000000000..bc155d504
--- /dev/null
+++ b/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-2-swift.svg	
@@ -0,0 +1,17 @@
+<svg width="300" height="169" viewBox="0 0 300 169" xmlns="http://www.w3.org/2000/svg">
+  <style>
+    text { fill: black; font-family: "HelveticaNeue", Helvetica, Arial, sans-serif; font-size: 9px; }
+    text.code { font-family: "Menlo", monospace; font-size: 8px; }
+    text.heading { font-size: 15px; }
+    text.param { font-family: "Menlo", monospace; font-weight: bold; font-size: 8.5px; }
+    text.lang { fill: #0066ff; font-weight: 600; }
+    rect { height: 10px; rx: 2px; ry: 2px; fill: #e3e3e3; }
+    rect.code { fill: #d8d8d8; }
+  </style>
+  
+  <text class="heading lang" x="295" y="17.3" text-anchor="end">Swift</text>
+    
+  <text class="heading" x="5" y="17.3">Parameters</text>
+  <text class="param" x="13.5" y="35.92">someValue</text>
+  <rect x="22.5" y="41.92" width="142.37"/>
+</svg>
diff --git a/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-2-swift~dark.svg b/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-2-swift~dark.svg
new file mode 100644
index 000000000..26ba158a6
--- /dev/null
+++ b/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-2-swift~dark.svg	
@@ -0,0 +1,15 @@
+<svg width="300" height="169" viewBox="0 0 300 169" xmlns="http://www.w3.org/2000/svg">
+  <style>
+    text { fill: white; font-family: "HelveticaNeue", Helvetica, Arial, sans-serif; font-size: 9px; }
+    text.code { font-family: "Menlo", monospace; font-size: 8px; }
+    text.heading { font-size: 15px; }
+    text.param { font-family: "Menlo", monospace; font-weight: bold; font-size: 8.5px; }
+    text.lang { fill: #0066ff; font-weight: 600; }
+    rect { height: 10px; rx: 2px; ry: 2px; fill: #404040; }
+  </style>
+  <text class="heading lang" x="295" y="17.3" text-anchor="end">Swift</text>
+    
+  <text class="heading" x="5" y="17.3">Parameters</text>
+  <text class="param" x="13.5" y="35.92">someValue</text>
+  <rect x="22.5" y="41.92" width="142.37"/>
+</svg>
diff --git a/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-3-objc.svg b/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-3-objc.svg
new file mode 100644
index 000000000..ce5f0fa24
--- /dev/null
+++ b/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-3-objc.svg	
@@ -0,0 +1,41 @@
+<svg width="300" height="189" viewBox="0 0 300 189" xmlns="http://www.w3.org/2000/svg">
+  <style>
+    text { fill: black; font-family: "HelveticaNeue", Helvetica, Arial, sans-serif; font-size: 9px; }
+    text.code { font-family: "Menlo", monospace; font-size: 8px; }
+    text.heading { font-size: 15px; }
+    text.param { font-family: "Menlo", monospace; font-weight: bold; font-size: 8.5px; }
+    text.lang { fill: #0066ff; font-weight: 600; }
+    rect { height: 10px; rx: 2px; ry: 2px; fill: #e3e3e3; }
+    rect.code { fill: #d8d8d8; }
+    rect.add { fill: rgba(0,180,60,0.2); height: 11px; }
+  </style>
+  <text class="heading lang" x="295" y="17.3" text-anchor="end">Objective-C</text>
+    
+  <text class="heading" x="5" y="17.3">Parameters</text>
+  <text class="param" x="13.5" y="35.92">someValue</text>
+  <rect x="22.5" y="41.92" width="142.37"/>
+  
+  <rect class="add" x="12.5" y="62.7" width="27.7" style="height: 9px"/>
+  <rect class="add" x="20.2" y="76.17" width="250.23"/>
+  <rect class="add" x="20.2" y="89.42" width="268.75"/>
+  <rect class="add" x="20.2" y="102.17" width="211.23"/>
+ 
+  <text class="param" x="13.5" y="69.67">error</text>
+  <text x="22" y="84.72">On output, a pointer to an error object that describes why the </text>
+  <text x="22" y="97.4">method failed, or </text>
+  <text class="code" x="92.69" y="97.4">nil</text>
+  <text x="109.73" y="97.4" > if no error occurred. If you are not interested </text>
+  <text x="22" y="110.65">in the error information, pass </text>
+  <text class="code" x="140.03" y="110.65">nil</text>
+  <text x="157.07" y="110.65"> for this parameter.</text>
+    
+  <rect class="add" x="178.5" y="154.5" width="96.6"/>
+  <rect class="add" x="4.5" y="167" width="52.5"/>
+    
+  <text class="heading" x="5" y="142.85">Return Value</text>
+  <rect x="5" y="155" width="172"/>
+  <text x="180.35" y="163.32">On failure, this method </text>
+  <text x="6" y="175.32">returns</text>
+  <text class="code" x="36.5" y="175.32">nil</text>
+  <text x="52" y="175.32">.</text>
+</svg>
diff --git a/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-3-objc~dark.svg b/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-3-objc~dark.svg
new file mode 100644
index 000000000..aaa2c1f09
--- /dev/null
+++ b/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-3-objc~dark.svg	
@@ -0,0 +1,40 @@
+<svg width="300" height="189" viewBox="0 0 300 189" xmlns="http://www.w3.org/2000/svg">
+  <style>
+    text { fill: white; font-family: "HelveticaNeue", Helvetica, Arial, sans-serif; font-size: 9px; }
+    text.code { font-family: "Menlo", monospace; font-size: 8px; }
+    text.heading { font-size: 15px; }
+    text.param { font-family: "Menlo", monospace; font-weight: bold; font-size: 8.5px; }
+    text.lang { fill: #0066ff; font-weight: 600; }
+    rect { height: 10px; rx: 2px; ry: 2px; fill: #404040; }
+    rect.add { fill: rgba(30,255,30,0.33); height: 11px; }
+  </style>
+  <text class="heading lang" x="295" y="17.3" text-anchor="end">Objective-C</text>
+    
+  <text class="heading" x="5" y="17.3">Parameters</text>
+  <text class="param" x="13.5" y="35.92">someValue</text>
+  <rect x="22.5" y="41.92" width="142.37"/>
+  
+  <rect class="add" x="12.5" y="62.7" width="27.7" style="height: 9px"/>
+  <rect class="add" x="20.2" y="76.17" width="250.23"/>
+  <rect class="add" x="20.2" y="89.42" width="268.75"/>
+  <rect class="add" x="20.2" y="102.17" width="211.23"/>
+ 
+  <text class="param" x="13.5" y="69.67">error</text>
+  <text x="22" y="84.72">On output, a pointer to an error object that describes why the </text>
+  <text x="22" y="97.4">method failed, or </text>
+  <text class="code" x="92.69" y="97.4">nil</text>
+  <text x="109.73" y="97.4" > if no error occurred. If you are not interested </text>
+  <text x="22" y="110.65">in the error information, pass </text>
+  <text class="code" x="140.03" y="110.65">nil</text>
+  <text x="157.07" y="110.65"> for this parameter.</text>
+    
+  <rect class="add" x="178.5" y="154.5" width="96.6"/>
+  <rect class="add" x="4.5" y="167" width="52.5"/>
+    
+  <text class="heading" x="5" y="142.85">Return Value</text>
+  <rect x="5" y="155" width="172"/>
+  <text x="180.35" y="163.32">On failure, this method </text>
+  <text x="6" y="175.32">returns</text>
+  <text class="code" x="36.5" y="175.32">nil</text>
+  <text x="52" y="175.32">.</text>
+</svg>
diff --git a/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-3-swift.svg b/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-3-swift.svg
new file mode 100644
index 000000000..994f41a56
--- /dev/null
+++ b/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-3-swift.svg	
@@ -0,0 +1,21 @@
+<svg width="300" height="189" viewBox="0 0 300 189" xmlns="http://www.w3.org/2000/svg">
+  <style>
+    text { fill: black; font-family: "HelveticaNeue", Helvetica, Arial, sans-serif; font-size: 9px; }
+    text.code { font-family: "Menlo", monospace; font-size: 8px; }
+    text.heading { font-size: 15px; }
+    text.param { font-family: "Menlo", monospace; font-weight: bold; font-size: 8.5px; }
+    text.lang { fill: #0066ff; font-weight: 600; }
+    rect { height: 10px; rx: 2px; ry: 2px; fill: #e3e3e3; }
+    rect.code { fill: #d8d8d8; }
+    rect.add { fill: rgba(0,180,60,0.2); height: 11px; }
+  </style>
+  
+  <text class="heading lang" x="295" y="17.3" text-anchor="end">Swift</text>
+    
+  <text class="heading" x="5" y="17.3">Parameters</text>
+  <text class="param" x="13.5" y="35.92">someValue</text>
+  <rect x="22.5" y="41.92" width="142.37"/>
+  
+  <text class="heading" x="5" y="84.85">Return Value</text>
+  <rect x="5" y="94.6" width="172"/>
+</svg>
diff --git a/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-3-swift~dark.svg b/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-3-swift~dark.svg
new file mode 100644
index 000000000..cef742e73
--- /dev/null
+++ b/Sources/docc/DocCDocumentation.docc/Documenting API with different language representations/params-3-swift~dark.svg	
@@ -0,0 +1,19 @@
+<svg width="300" height="189" viewBox="0 0 300 189" xmlns="http://www.w3.org/2000/svg">
+  <style>
+    text { fill: white; font-family: "HelveticaNeue", Helvetica, Arial, sans-serif; font-size: 9px; }
+    text.code { font-family: "Menlo", monospace; font-size: 8px; }
+    text.heading { font-size: 15px; }
+    text.param { font-family: "Menlo", monospace; font-weight: bold; font-size: 8.5px; }
+    text.lang { fill: #0066ff; font-weight: 600; }
+    rect { height: 10px; rx: 2px; ry: 2px; fill: #404040; }
+    rect.add { fill: rgba(0,180,60,0.2); height: 11px; }
+  </style>
+  <text class="heading lang" x="295" y="17.3" text-anchor="end">Swift</text>
+    
+  <text class="heading" x="5" y="17.3">Parameters</text>
+  <text class="param" x="13.5" y="35.92">someValue</text>
+  <rect x="22.5" y="41.92" width="142.37"/>
+  
+  <text class="heading" x="5" y="84.85">Return Value</text>
+  <rect x="5" y="94.6" width="172"/>
+</svg>