[docs] Mark new functions as requiring Stacks 2.1 in vm::docs

[gregorycoppola]

Is your feature request related to a problem? Please describe. The problem is that in the vm::docs, we now have functions, like "buff-to-int-le", that require Stacks 2.1. But, we do not have a nice way to annotate these. Currently, I have just put in plain text:

Note: This function is only available starting with Stacks 2.1.

However, we can consider doing something nicer, like having a little "chip" or something.

Describe the solution you'd like This is up for discussion. We could have a little "chip" that says "Stacks 2.1".

Additional context See the discussion in https://github.com/blockstack/stacks-blockchain/pull/2691#discussion_r653085585

[jcnelson]

Estimate 1-2 days to completion. We'd want this to be machine-checkable like the other aspects of the clarity docs.

[pavitthrap]

I prefer using the distinction of which clarity version each function is: Clarity1 / Clarity2.

Also, it would be nice to make the functions alphabetical as well. This would require a change to make_all_api_reference (sorting functions)

let mut function_enums: Vec<_> = NativeFunctions::ALL.to_vec();
function_enums.sort_by(|x, y| x.get_name().cmp(&y.get_name()) );

let mut functions: Vec<FunctionAPI> = function_enums
    .iter()
    .map(|x| make_api_reference(x))
    .collect();

[gregorycoppola]

How do we actually make a "little chip" that says Clarity1 vs Clarity2? Does this amount to adding enums to FunctionAPI and KeywordAPI?

[gregorycoppola]

@kantai @jcnelson @pavitthrap

Is the idea to add the following fields and then fill them in for each instance?

#[derive(Serialize, Clone)]
struct KeywordAPI {
    ...
    /// The version where this keyword was first introduced.
    version: ClarityVersion,
}

#[derive(Serialize)]
struct FunctionAPI {
    ...
    /// The version where this function was first introduced.
    version: ClarityVersion,
}

[kantai]

I think you should be able to add a new field to FunctionAPI and KeywordAPI and then "automatically" have those fields filled in by modifying make_for_simple_native, make_for_special, make_keyword_reference, to use the .get_version() method of the NativeFunctions and NativeKeywords to get each function or keyword's version.

https://github.com/stacks-network/stacks-blockchain/blob/next/clarity/src/vm/docs/mod.rs#L654

That way, we don't need to duplicate information in the documentation about what version each method is defined in (because that's already specified when the functions and keywords are declared in the code).