Solidity has a pretty neat cheatsheet doc that devs can use to get upto speed or do a quick reference if they ever need to. Since Huff has limited documentation currently, it's probably a good idea to have a community-built cheatsheet. This will be different from evm.codes since Huff uses its own wrappers around the opcodes.

ref. https://docs.soliditylang.org/en/latest/cheatsheet.html

Currently, there is no explaining of the importing rules in the docs, maybe we should add this, with a brief explanation of forge remappings (link to their docs?), or relative importing.

Overview

Create Footer on homepage, with links to github, twitter, discord, copyright, etc.

"we have to an understanding..." -> "we need to have an understanding..."
https://docs.huff.sh/tutorial/hello-world/

The example given for the Jump Labels section in Huff By Examples, is causing stack underflow error on the mstore opcode under the success label. You can try it out here quickly.

It seems to me that 0x00 mstore part is unnecessary as the following line simply returns the "Hello, World!" string already stored in the memory (with some weird characters in the beginning cause of the padded zeroes which could be fixed with 0x0d 0x13 return).

Also, the comments representing the state of the stack seem a bit off.

Following is how I think the example should have been:

#define macro MAIN() = takes (0) returns (0) {
    // Store "Hello, World!" in memory
    0x48656c6c6f2c20576f726c6421 // ["Hello, World!"]
    0x00 mstore // [ ]

    // Jump to success label, skipping the revert statement
    success     // [success_label_pc]
    jump        // [ ]

    // Revert if this point is reached
    0x00 0x00 revert

    // Labels are defined within macros or functions, and are designated
    // by a word followed by a colon. Note that while it may appear as if
    // labels are scoped code blocks due to the indentation, they are simply
    // destinations to jump to in the bytecode. If operations exist below a label,
    // they will be executed unless the program counter is altered or execution is
    // halted by a `revert`, `return`, `stop`, or `selfdestruct` opcode.
    success:
        0x0d 0x13 return
}

Issue:

https://github.com/huff-language/huff-docs/tree/main/src/tutorial/evm-basics

README.md Resources hyperlink returns 404

https://github.com/huff-language/huff-docs/blob/main/src/tutorial/evm-basics/resources/overview

Potential fix:

Change the Resources hyperlink from

https://github.com/huff-language/huff-docs/blob/main/src/tutorial/evm-basics/resources/overview

to

https://docs.huff.sh/resources/overview/

It is still confusing when to use takes and returns. Include a dedicated section within the tutorial to address this.

Spawned from #60

What's the status of Etherscan support?

Etherscan has a lot of great features for verified contracts such as Read/Write Contract, ABI, natspec, etc. Since huffc generates artifacts, Etherscan should have most of what it needs. The only thing that might be missing is natspec, which can be solved by recommending that the natspec be placed next to the ABI definitions rather than the macro definitions (this would allow it to be plugged into doc generators in general).

Overview

Currently, there are only two resources listed in https://docs.huff.sh/resources/

We should split resources into at least two sections, one being official Huff Language repositories, with any other sections being third party and all other resources.

The default content width is very small. The content appears squished in the center of my screen with lots of whitespace on either side and then the content itself has to be horizontally scrolled.

These vuepress docs links might help:
vuejs/vuepress#1867
https://vuepress.vuejs.org/config/#index-styl

Overview

Add a section to the style guide detailing the standard used in huffmate for natspec comments.

• At the top of the file with @title, @notice, and @author(s)
• Above macros/functions with @notice, @dev (optional), @param (if there are any), and @return (if there are any)

Does this mean 'make' the tutorial?

There is no mention of the __VERBATIM built-in in the docs

Would love to see this in the docs somewhere.

https://vexil.notion.site/Immutables-in-Huff-7db5cb6436494fa195e73c43e989b17d

Just so that if someone looks for immutable in the docs search bar, this comes up.

Overview

Following what's outlined in the tutorials overview, the Huff Docs should demonstrate how to write a simple "Hello World" contract.

Warning

Blocked by #14 due to large-scale docs refactoring

EDIT: No longer blocked!

In the Huff by Example section of the docs under Macros and Functions > Macros > Macro Arguments it is mentioned that "Macro arguments may be one of: label, opcode, literal, or a constant" however it doesn't currently seem to be possible to use opcodes as macro arguments (as of huffc v0.2.0, latest version at time of writing).

Specifically the lexer module of the Huff compiler does not recognize opcodes outside of the body of macros / functions at the moment (lexer reference). Personally I haven't dived deep enough into the codegen module so I'm unsure if there's any logic to support opcode args there already.

While this could be quite a useful feature in certain instances, it doesn't seem to be possible just yet.

huff.sh domain expired

Overview

There should be an official style guide in the Huff Docs since the language is low-level, and not necessarily intuitive.

Fortunately, we have one implemented in Notion, we just need to port the notion doc to these docs: https://coherent-wolfberry-04a.notion.site/huff-lib-Styling-9c2ceaa795934c38be0b2f2d10042fe9

Overview

In huff-by-example, the Builtin section example uses jumptables, but they are not explained until later on in the doc. We should remove the CONDITIONAL and CONDITIONAL_TEST parts of the Builtin Section Example (linked above) h/t @devtooligan

I learned by looking at the code of huff-rs that it is possible to pass constants as arguments to a macro. There is no mention of this in the docs yet

Work on building a standard for contributing to the huff language!