FLIP - Interaction Template Cadence Doc

[JeffreyDoyle]

FLIP - Interaction Template Cadence Doc

[bjartek]

Since there is an existing standard i think we should use that to avoid confusion. It also becomes a lot easier to generate html docs for all cdc files if we do.

Since we need more fields in flix like translations i propose we use a seperate translation file for that. This could also be useful for other cadence doc. Like translating documentation for cadence contracts.

[JeffreyDoyle]

@bjartek
Re:

Since we need more fields in flix like translations i propose we use a seperate translation file for that. This could also be useful for other cadence doc. Like translating documentation for cadence contracts.

This is a great idea, as it enables developers to update their Interaction Template Cadence Doc without changing the content of their Cadence scripts / transactions, which prevents issues to do with a transaction needing to be re-allowlisted to be compatible with certain wallet providers, for example.

I updated the FLIP with a new section on how Interaction Template Cadence Doc could be specified in a separate JSON file from the Cadence transaction / script.

[turbolent]

Really like this idea in general 👍

[nvdtf]

Since we need more fields in flix like translations i propose we use a seperate translation file for that. This could also be useful for other cadence doc. Like translating documentation for cadence contracts.

@bjartek I think keeping the documentation with the code should be very important. The code will make its way into the user's wallet history and block explorers, and having relevant docs beside the code makes it readable in the future. Pulling the relevant docs for a given piece of code from all places (like wallet tx history) might be impossible. I also imagine the size of this documentation to be small, so if a developer writes extra docs in separate files I imagine it should be walls of text and graphs to go a bit more into internals.
Maybe there is a middle-ground were the most important fields stay with the interaction and some others are moved into a separate file?

which prevents issues to do with a transaction needing to be re-allowlisted to be compatible with certain wallet providers

I think this means that white-listing algorithms should be smarter to avoid checking comments. The same problem manifests in different ways, like an extra new line at the end of transaction. I know Dapper updated their whitelisting algo to cover these cases but a smarter algo will also exclude comments from checks.

[bjartek]

@nvdtf i also agree that the primary language for the flix should be in the file. I am talking more about translations.

We have also spoken about the pin of the interaction to be derived from the AST without comments, but I am not sure how feasible that is. Comment?

[bjartek]

I think having an annotation in the doc tag for the name of the interaction actually makes sense.

I would also argue that the author/composer/writer/supplier of the interaction should be there.

So that would be

@name getUsers
@author .find

As @nvdtf said if these things are there when transactions are sent it becomes so much easier to analyse and know where things originate from.

[bthaile]

I updated Cadence comment examples, added a script example and updated translation examples.

[JeffreyDoyle]

Updates according to feedback from the Interaction Template working group on August 14 2023

[bthaile]

Updated flip, should have addressed all comments:

1. change argument to parameter in reference to flix 1.1
2. removed "translate"
3. updated version to f_version

Leading thought is to build tooling around this flip to determine if any changes are needed before this is merged to main.

[bthaile]

approved

[bthaile]

lgtm

[bthaile]

@bjartek mentioned using Cadence docs parsing instead of having flix specific properties in Cadence comments.
onflow/flixkit-go#20 (comment)

Cadence docs parsing has to do with converting comments to markdown for documentation. I'm mixed on this approach.
There are benefits of using existing cadence tools. I think this would be a good approach if no modifications are needed to cadence doc parser.

Unfortunately I think we'd need to add guidance on how the Cadence dev needs to write there doc comment so that the flix json is generated correctly. Or add more support for tags in the Cadence doc parser so usage is clear to the Cadence dev.

Could get parameter and return values from Cadence doc parser. Also could get the top level description and parameter description. Would have to use name as parameter Title. There would have to be a convention to get top level Title

[turbolent]

Following up from the discussion yesterday:
As an alternative to defining the interaction metadata using documentation comments ("docstrings"), Cadence provides pragmas (syntax is '#' expression) which are parsed, but ignored by the type checker and interpreter. Pragmas can be e.g. used for directives (e.g. #allowAccountLinking), or here to "annotate" parts of the program.

This would have the benefit of not having to define a new syntax for encoding the metadata in comments, having to write a parser for it, and users having to learn a new syntax. With pragmas, the syntax is simply Cadence, and no new parser has to be implemented.

This could for example look like (straw man syntax):

#interaction(
    version: "1.1.0",
    title: "Transfer Tokens",
    description: "Transfer tokens from one account to another",
    language: "en-US",
    parameters: [
        Parameter(
            name: "amount", 
            title: "Amount", 
            description: "The amount of FLOW tokens to send"
        ),
        Parameter(
            name: "to", 
            title: "To",
            description: "The Flow account the tokens will go to"
        )
    ]
)
transaction(amount: UFix64, to: Address) {
   // ...

The syntax used in the example is for illustration-purposes only, and is not a concrete proposal. Here, the pragma uses a function call expression. In a sense, this is similar to JSON, where data is encoded using JS syntax.

[bthaile]

Updated FLIP to use Cadence pragma for interaction template metadata.