Historically, a function could have distinct description of itself "overall" from a description of its return value:
>> sum-two: func [
"This function sums two integers"
return: [integer!] "Sum of a and b"
a [integer!]
b [integer!]
][
return a + b
]
>> help sum-two
USAGE:
SUM-TWO a b
DESCRIPTION:
This function sums two integers
RETURNS: [integer!]
Sum of a and b
ARGUMENTS:
a [integer!]
b [integer!]
At one point, the HELP information was resident in a special "adjunct" object, which had type information and descriptions for every field. With time, this evolved to where PARAMETER! objects held the type spec blocks and descriptions. You can just ask for the parameter, and the string can be picked out of it.
This applied to returns as well (which aren't visible as named fields to the outside, but have to be gotten by RETURN OF)
>> param: return of sum-two/
== &[parameter! [integer!]]
>> param.spec
== [integer!]
>> param.text
== "Sum of a and b"
But... Where Does The Overall Description Go?
The overall description is a bit of a thorn, there's nowhere to put it. So it still gets put in a magic "adjunct" object, whose creation is extra cost:
>> adjunct of sum-two/
== &[object! [
description: "This function sums two integers"
]]
The logic for creating this object is fairly hairy.
Could We Say The RETURN Text Is The Description?
I've always had a bit of trouble figuring out what and when to say something about the return value, that's distinct from the description.
There are some cases where you might want to, but really that just speaks to "sometimes you want a longer description".
>> sum-two: func [
"This function sums two integers, a and b"
return: [integer!]
a [integer!]
b [integer!]
][
return a + b
]
Plus now that LAMBDA can specify its return, there's a place to put the information on that PARAMETER! that it stows in a special place (that isn't optimized as a FRAME! slot, since there's no word slot for RETURN)... to answer the RETURN OF question.
I know Red has favored putting RETURN: at the end, and despite me often feeling like it would simplify the code to not have the flexibility, I have been permissive about where to put the return information so far. It's hard to say you shouldn't be able to do that if you wanted to.
Anyway, this would take it one step further, to let you actually push the description of the function to the end as well:
>> sum-two: lambda [
a [integer!]
b [integer!]
[]: "This function sums two integers, a and b"
[integer!]
][
a + b
]
>> sum-two: lambda [
a [integer!]
b [integer!]
[]: [integer!]
"This function sums two integers, a and b"
][
a + b
]
This Would Be A Big Simplification
The core wouldn't make ADJUNCT objects, so that would be free entirely for user use to associate objects with functions... and function generation would be cheaper.
You get more flexibility, at the cost of not being able to describe the return result independently from the function as a whole... but... as I said, just write a longer description. 