add documentation guidelines

[holyfuchs]

copy paste from the docgen tool:
https://github.com/onflow/cadence-tools/blob/5e26b7903dfe7bedc273699b8e71532273ff93e0/docgen/README.md

[holyfuchs]

docgen seems to be no longer working and isn't maintained.

[turbolent]

Docgen was a side-project from Supun. It hasn't been prioritized, so might need some love. If it would be helpful for FCM, we should look into what would be needed to make it work again.

Even if there's currently no tooling for documentation, IMHO the code should still be documented. In particular, types and functions should still be documented with docstrings.

Could we maybe restore the branch and reopen the PR? It looks great to me!

[jordanschalm]

the code should still be documented. In particular, types and functions should still be documented with docstrings.

💯

Might make the most sense to add these documentation primarily to the general-purpose Cadence skill: https://github.com/onflow/flow-ai-tools/tree/main/plugins/flow-dev/skills/cadence-lang.

[turbolent]

Might make the most sense to add these documentation primarily to the general-purpose Cadence skill: onflow/flow-ai-tools@main/plugins/flow-dev/skills/cadence-lang.

Agreed, opened onflow/flow-ai-tools#26

[holyfuchs]

Ofc the code needs to be documented!
The problem is the LSP does not support the @PARAM format

It will be displayed like this:

This is the description of the function. This function adds two values.
@param a: First integer value to add @param b: Second integer value to add @return Addition of the two arguments a and b

what is does support is markdown so I would suggest is this:

Input

/// Consumes one unit of allowance and creates a new yield vault.
/// Panics if allowance is exhausted.
///
/// **Parameters**
/// - `name`: Name of the registered strategy to create a vault for.
///
/// **Returns** A new `YieldVault` to be saved in the caller's storage.
access(all) fun createYieldVault(name: String): @{FlowYieldVaultsInterfaces.YieldVault} {

Output

Type

fun (name: String): @{FlowYieldVaultsInterfaces.YieldVault}

Documentation

Consumes one unit of allowance and creates a new yield vault. Panics if allowance is exhausted.

Parameters

• name: Name of the registered strategy to create a vault for.

Returns A new YieldVault to be saved in the caller's storage.

[turbolent]

Ah, I see, thanks for pointing out the issue with using the format that docgen expects. We can improve the language server to add support for the existing format, but let's not make that a blocker for this project.

The proposed format looks good. BTW Swift uses very similar Markdown: https://www.swift.org/documentation/docc/writing-symbol-documentation-in-your-source-files#Describe-the-Parameters-of-a-Method.

[turbolent]

Implemented the pre-processing/formatting of the annotations in the language server: onflow/cadence-tools#635