Distinguish functions from syntactic forms

[njordhov]

The documentation and related material conflates Clarity functions with syntactic forms. They should be clearly distinguished to avoid confusion and aid developers in using the language.

For example, the Clarity reference says:

The let function accepts a list of variable name and expression pairs, evaluating each expression and binding it to the corresponding variable name.

However. let is not a function but a syntactic form.

Although functions and syntactic forms share the S-expression syntax, syntactic forms are evaluated in custom ways rather than according to the convention for functions, where each argument is evaluated into a value during function invocation.

Other syntactic forms include the many define-* constructs, which don't call their evaluated arguments like normal functions but rather are evaluated in special ways. Additional examples of syntactic forms are listed on https://github.com/blockstack/docs/issues/495

[kantai]

@njordhov -- should this just be a documentation issue for the docs repo? Or is this an issue in the generated documentation in the stacks-blockchain repo as well?

[njordhov]

should this just be a documentation issue for the docs repo? Or is this an issue in the generated documentation in the stacks-blockchain repo as well?

@kantai The conflation of functions and syntactic forms is primarily an issue with the documentation, although the confusion spreads to tutorials and general discussion of the language. Although the sources for the auto generated documentation obviously is aware of the distinction by encoding for Special forms, there are still inconsistencies:

• and shortcuts thus is not a function, while is-eq behaves like a function by having all its arguments evaluated in order https://github.com/blockstack/stacks-blockchain/blob/master/src/vm/docs/mod.rs#L397
• let is not a function https://github.com/blockstack/stacks-blockchain/blob/151e06ec319a0460631c0083a5618a2f1cce2c9a/src/vm/docs/mod.rs#L421
• var-get does not evaluate its argument thus not a function https://github.com/blockstack/stacks-blockchain/blob/151e06ec319a0460631c0083a5618a2f1cce2c9a/src/vm/docs/mod.rs#L431
• likewise for var-set https://github.com/blockstack/stacks-blockchain/blob/151e06ec319a0460631c0083a5618a2f1cce2c9a/src/vm/docs/mod.rs#L441
• and so on.