Function Specs: Merge TEXT! Into Parameter Specs?

Development Functions
1

I wrote about the new feature of being able to put descriptions of what each type does in a type spec block:

I like this. Though it made me start to wonder...

If TEXT! strings are legal in the spec, what if we said that the spec could be either a TEXT! or a BLOCK!, but not both?

We've been burdened with a stylistic question about whether strings come before or after the parameter:

foo: func [
    arg "Does your text string go here"
       [type1! type2!]
][
    ...
]

foo: func [
    arg [type1! type2!]
        "Or does your text string go here?"
][
    ...
]

But this points to another possibility:

foo: func [
    arg [
        "Maybe like this?"
        type1! type2!
    ]
][
    ...
]

I definitely can see some upsides of this.

Specifically, that there'd be no param.text ... only param.spec.

This would be an acknowledgment that there's no longer a 1:1 mapping between parameters and text strings. Rather, any descriptions would be considered "part of the spec"...and if you were going to write a HELP-like function you would never lean on the separation, assuming the interesting text wasn't in the spec.

It would make it more discoverable that you can put strings in on a per-type basis.

Function spec parsing becomes less wishy-washy.

Downside is that a string and types becomes less succinct.

param [
   "Some parameter description"
   type1! type2!
]

vs.

param "Some parameter description"
   [type1! type2!]

That's 4 lines compared to 1. I kind of can't accept that.

But we could still push the text into the spec in the implementation as if you had put the text in the block, so that there's only param.spec and not param.text

Unfortunately... that breaks the current test for "unconstrained" parameters, which is when param.spec is NULL.

Well... unconstrained? could be a function that tests PARAMETER! for if there were only text strings in the spec. A bit different than "if not param.spec [...]" but more intentional. And maybe solves a bug that nothing checks today that you didn't make a parameter spec that was just strings. (Though this would mess with return: [] as being "divergent", as it would have to mean "unconstrained"...)

Such changes may not be a good idea, but it's something to think about.

:thinking: