Function title doc string (modifies) convention is misleading, could be tweaked

[rebolbot]

Submitted by: BrianH

There is currently a convention for functions that modify their arguments to put "(modifies)" in their title doc string. However, this is not a good convention for two reasons:

1) Which argument is modified? In these functions certain arguments are modified and others aren't; the difference is important, more important than the general idea that the function is a modifying one. Just having a "(modifies)" in the title string isn't enough information, and may be interpreted as meaning that all arguments are modified.

2) There is a 72-char limit on the length of the title doc string (see #1843), so every character counts. It is often a good idea to move the information about specific arguments to those arguments' doc strings to make the best use of the space available.

It would be better to instead say which arguments are modified with a "(modified)" label on the argument doc string. Then it would be clear which are modified or not, and would give us more room in the title string.

Related: #1843. We can work on both at the same time.

^{CC - Data [ Version: alpha 110 Type: Issue Platform: All Category: Documentation Reproduce: Always Fixed-in:alpha 112 ]}

[rebolbot]

Submitted by: BrianH

At least these functions are affected:

>> foreach [w v] sort/skip body-of lib 2 [if all [any-function? :v string? first spec-of :v find first spec-of :v "(modifies)" 1 < length? map-each w words-of :v [either refinement? w [()] [w]]] [print [to-word w type? :v]]]
alter function!
append action!
bind native!
change action!
decloak native!
detab native!
encloak native!
entab native!
insert action!
lowercase native!
new-line native!
poke action!
remove action!
remove-each native!
reverse action!
sort action!
swap action!
take action!
uppercase native!
== none

Plus TRIM (#1841) and REPLACE (#1842). REPLACE needs it in particular because its title doc string is already 72 characters long, so there is no room to add "(modifies)" to it.

[rebolbot]

Submitted by: Carl

A good suggestion, since it is the arg begin modified, and SWAP is a good example where both series are modified.

The 72 char limit is a separate discussion.