starknet-io / starknet-docs

The repo for Starknet's developer documentation. Includes contribution guidelines and the Starknet documentation supplementary style guide

https://docs.starknet.io/

112 stars 159 forks source link

feat: add page for describing cairo builtins #1202

Closed xiaolou86 closed 1 month ago

xiaolou86 commented 3 months ago

Description of the Changes

Closes #1126
Add pages for describing cairo builtins

PR Preview URL

After you push a commit to this PR, a preview is built and a URL to the root of the preview appears in the comment feed.

Paste here the specific URL(s) of the content that this PR addresses.

Check List

[x] Changes have been done against main branch, and PR does not conflict
[x] PR title follows the convention: <docs/feat/fix/chore>(optional scope): <description>, e.g: fix: minor typos in code

This change is

xiaolou86 commented 3 months ago

@stoobie I finished the doc, please help me to review. Thank you very much.

stoobie commented 3 months ago

@xiaolou86 Thank you! I've forwarded this on for a technical review. Once that is done, I'll go over it and edit or make suggestions.

stoobie commented 3 months ago

@xiaolou86 Here's the tech review feedback I received:

the original Caior0 docs describes builtins better. (From me (stoobie): That doesn't mean you should just copy. I don't like the word "vanilla", the grammar is not great, and the page doesn't follow the Starknet docs writing guidelines and our style guide.)
builtins are not a “basic language construct”, they have a concrete definition
arithmetic operations aren’t builtins (only builtins are the ones listed on the docs list in the fee page)
some of the code is referring to Cairo0 (e.g. hash2, no such function in Cairo 1)
no mention of builtins being used under the hood in Cairo 1 (you can’t use them directly, there are libfuncs and corelib functions that make use of them)

It would be good to provide a code example of a builtin vs accomplishing the same thing in standard Cairo.

xiaolou86 commented 3 months ago

ok, I will update the docs.

xiaolou86 commented 3 months ago

@stoobie please help to review again.

stoobie commented 3 months ago

Please mention that you don't need to do anything to use a builtin. The library you use should automatically scan your code and use a builtin where appropriate. I'm not 100% sure if I got this right, so please wait for a confirmation from @ArielElp.

Also, the only builtins that you should have on this page are the ones [isted in on the docs list in the fee page in Table 1. Amount of gas used per Cairo step or per each time a Cairo builtin is applied)

xiaolou86 commented 3 months ago

Please mention that you don't need to do anything to use a builtin. The library you use should automatically scan your code and use a builtin where appropriate. I'm not 100% sure if I got this right, so please wait for a confirmation from @ArielElp.

All right.

Also, the only builtins that you should have on this page are the ones [isted in on the docs list in the fee page in Table 1. Amount of gas used per Cairo step or per each time a Cairo builtin is applied)

I think I have the only ones on this page, but I am not much sure.

Thank you very much.

stoobie commented 2 months ago

@xiaolou86 After reviewing this with our expert, I found that we were on the wrong track. I created a new PR (#1243) with the necessary info.

Feel free to review it and make suggestions or ask questions if anything is unclear. After the new PR is merged, I'll settle with you on OnlyDust.