Add a documentation section for Concepts/Finalize

[kpandl]

Closes #283

[collinc97]

LGTM

[collinc97]

Going to wait for @apruden2008 and @craigjson 's reviews before merging to production and closing the issue.

[craigjson]

I see some repeated information in the existing Language/Functions section with this one.

Does it make sense to move the entire Functions section into a new page and document all of them in more detail, we can link to this new section in the existing portion in the Language section.

[collinc97]

I see some repeated information in the existing Language/Functions section with this one.

Does it make sense to move the entire Functions section into a new page and document all of them in more detail, we can link to this new section in the existing portion in the Language section.

Is the repeated information inconsistent?

How large of a change to the existing language guide would be needed to modify the existing docs @craigjson ?

Can you give @kpandl a checklist of line numbers and paragraphs to address the feedback?

[kpandl]

Thank you for the feedback, @craigjson and @collinc97.

The finalize file contains more detailed information on finalize than the language file. So all of the information of the language file is also in the finalize file, but not necessarily the other way. From my understanding, the repeated information is consistent.

Speaking of line numbers, the following line numbers in the finalize file add information over the language file:

• Line 7 (used to run computations on chain, primary purpose of public on chain state/mappings initiation/change)
• Line 14 (Aleo network nodes, only code in finalize updates mappings, only program can write into its own mapping, Aleo network nodes can read public state)
• Line 16 (explanation of the example code)
• Line 52 (explanation when finalize may be unnecessary)

Speaking of line numbers in the language file, information from all lines on finalize (366-413) is also contained in the finalize file.

Going forward, one way to address it would be by making the information in the finalize file more dense, for example by removing the code from lines 377-413 (as the code is also in the finalize section and explained in more depth) and mention in the sentence with the link (line 376) that there is a code example. However, the description of finalize in the language section may then be less consistent with the description of other functions which have an example. I don't think we should remove any information on finalize from lines 368-374.
Alternatively, we could include all of the information of the finalize file in the language file, if the standalone finalize file is not necessary to have (I think this is my preferred option right now).
@craigjson yes another alternative would be to have a separate functions section if you see room for more detailed descriptions on the other functions.

What do you think? Happy to implement the changes

[craigjson]

I don't see an issue with the Finalize file being a super-set of the language/finalize portion.

The thing I noticed was that from a structure POV, the standalone Finalize section is lower level than any of the other sub-topics under Leo.

Alternatively, we could include all of the information of the finalize file in the language file, if the standalone finalize file is not necessary to have (I think this is my preferred option right now).

This is my favorite solution also.

If finalize is the only function that is getting more detailed information, keeping things consistent and in one place would be my preference.

[collinc97]

LGTM