From 59e66fc295e2307109823f2a38ae6b29a2743847 Mon Sep 17 00:00:00 2001
From: Lilith Orion Hafner <lilithhafner@gmail.com>
Date: Fri, 28 Feb 2025 07:59:02 -0600
Subject: [PATCH 1/6] Document how return types and return values should be
 used in docstrign signature lines

---
 doc/src/manual/documentation.md | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/doc/src/manual/documentation.md b/doc/src/manual/documentation.md
index a11d41d441b73..895cb751b4b62 100644
--- a/doc/src/manual/documentation.md
+++ b/doc/src/manual/documentation.md
@@ -81,6 +81,37 @@ As in the example above, we recommend following some simple conventions when wri
    accepts many keyword arguments, only include a `<keyword arguments>` placeholder in the signature
    (i.e. `f(x; <keyword arguments>)`), and give the complete list under an `# Arguments` section
    (see point 4 below).
+
+   The return value or return type should be included in the signature if necessary.
+   Often the return type could vary widely depending on the input, and in that case should
+   not be included in the signature.
+
+   ```julia
+   # No return value is needed
+   """
+      sum(itr; [init])
+
+   ...
+   """
+
+   # The return type is critical to the semantics of this function
+   """
+      vec(x::AbstractArray)::AbstractVector
+
+   ...
+   """
+
+   # Naming and destructuring the return value clarifies the semantics of this function
+   """
+      splitdir(path::AbstractString) -> (dir::AbstractString, file::AbstractString)
+   ...
+   """
+   ```
+   When included, a return type should be written after the signature, separated by `::`
+   and a named return value should be separated by ` -> ` with a space on both sides.
+   Return types and return values should be valid Julia expressions when possible.
+   Macro docstring signatures that annotate return types or return values should use
+   parentheses to clarify where the macro arguments end and return type or return value begins.
 2. Include a single one-line sentence describing what the function does or what the object represents
    after the simplified signature block. If needed, provide more details in a second paragraph, after
    a blank line.

From bf732933cec01527e8b424c8ca3088694ddccd38 Mon Sep 17 00:00:00 2001
From: Lilith Orion Hafner <lilithhafner@gmail.com>
Date: Fri, 28 Feb 2025 11:21:48 -0600
Subject: [PATCH 2/6] Update doc/src/manual/documentation.md

Co-authored-by: Neven Sajko <4944410+nsajko@users.noreply.github.com>
---
 doc/src/manual/documentation.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/src/manual/documentation.md b/doc/src/manual/documentation.md
index 895cb751b4b62..0fd7322ad8244 100644
--- a/doc/src/manual/documentation.md
+++ b/doc/src/manual/documentation.md
@@ -107,8 +107,8 @@ As in the example above, we recommend following some simple conventions when wri
    ...
    """
    ```
-   When included, a return type should be written after the signature, separated by `::`
-   and a named return value should be separated by ` -> ` with a space on both sides.
+   When included, a return type should be written after the signature, separated by `::`,
+   while a named return value should be separated by ` -> `, with a space on both sides.
    Return types and return values should be valid Julia expressions when possible.
    Macro docstring signatures that annotate return types or return values should use
    parentheses to clarify where the macro arguments end and return type or return value begins.

From 844653ad6e10502da09d77e69cd1bedbc3cfaa69 Mon Sep 17 00:00:00 2001
From: Lilith Orion Hafner <lilithhafner@gmail.com>
Date: Fri, 28 Feb 2025 11:22:37 -0600
Subject: [PATCH 3/6] Update doc/src/manual/documentation.md

Co-authored-by: Neven Sajko <4944410+nsajko@users.noreply.github.com>
---
 doc/src/manual/documentation.md | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/doc/src/manual/documentation.md b/doc/src/manual/documentation.md
index 0fd7322ad8244..f37d5c35968e2 100644
--- a/doc/src/manual/documentation.md
+++ b/doc/src/manual/documentation.md
@@ -82,9 +82,7 @@ As in the example above, we recommend following some simple conventions when wri
    (i.e. `f(x; <keyword arguments>)`), and give the complete list under an `# Arguments` section
    (see point 4 below).
 
-   The return value or return type should be included in the signature if necessary.
-   Often the return type could vary widely depending on the input, and in that case should
-   not be included in the signature.
+   Use this style to document the return type or give the return value a name:
 
    ```julia
    # No return value is needed

From 621e38b959eb4a13b9c85b9725010a550e105499 Mon Sep 17 00:00:00 2001
From: Lilith Orion Hafner <lilithhafner@gmail.com>
Date: Fri, 28 Feb 2025 11:23:02 -0600
Subject: [PATCH 4/6] Update documentation.md

---
 doc/src/manual/documentation.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/src/manual/documentation.md b/doc/src/manual/documentation.md
index f37d5c35968e2..41f130d25bcac 100644
--- a/doc/src/manual/documentation.md
+++ b/doc/src/manual/documentation.md
@@ -85,7 +85,7 @@ As in the example above, we recommend following some simple conventions when wri
    Use this style to document the return type or give the return value a name:
 
    ```julia
-   # No return value is needed
+   # No return value is needed (this is the most common case)
    """
       sum(itr; [init])
 

From dba2f5b188b8f715d338b1a7e9af5155d2109e53 Mon Sep 17 00:00:00 2001
From: Lilith Orion Hafner <lilithhafner@gmail.com>
Date: Thu, 13 Mar 2025 11:01:48 -0500
Subject: [PATCH 5/6] Update documentation.md

---
 doc/src/manual/documentation.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/src/manual/documentation.md b/doc/src/manual/documentation.md
index 41f130d25bcac..c07d60bf59aec 100644
--- a/doc/src/manual/documentation.md
+++ b/doc/src/manual/documentation.md
@@ -85,7 +85,7 @@ As in the example above, we recommend following some simple conventions when wri
    Use this style to document the return type or give the return value a name:
 
    ```julia
-   # No return value is needed (this is the most common case)
+   # Naming the return value or its type is not necessary (this is the most common case)
    """
       sum(itr; [init])
 

From 98154aaef03dc0572c8f3fb315bca70ef6cbff08 Mon Sep 17 00:00:00 2001
From: Lilith Orion Hafner <lilithhafner@gmail.com>
Date: Sun, 23 Mar 2025 07:21:16 -0500
Subject: [PATCH 6/6] Minor wording updates

---
 doc/src/manual/documentation.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/src/manual/documentation.md b/doc/src/manual/documentation.md
index c07d60bf59aec..ebb41d0ccb485 100644
--- a/doc/src/manual/documentation.md
+++ b/doc/src/manual/documentation.md
@@ -92,14 +92,14 @@ As in the example above, we recommend following some simple conventions when wri
    ...
    """
 
-   # The return type is critical to the semantics of this function
+   # The return type is easily documented and critical to the semantics of this function
    """
       vec(x::AbstractArray)::AbstractVector
 
    ...
    """
 
-   # Naming and destructuring the return value clarifies the semantics of this function
+   # Naming and/or destructuring the return value clarifies the semantics of this function
    """
       splitdir(path::AbstractString) -> (dir::AbstractString, file::AbstractString)
    ...