From e0fc53a10e69abd55ad563f98477bcf9568d76b0 Mon Sep 17 00:00:00 2001
From: sandbubbles <160503471+sandbubbles@users.noreply.github.com>
Date: Wed, 20 Nov 2024 20:42:34 +0000
Subject: [PATCH] chore[docs]: mention the `--venom` flag in venom docs (#4353)

add some notes to the relevant docs that `venom` is an alias for
`experimental-codegen`
---
 docs/compiling-a-contract.rst    |  7 ++++++-
 docs/structure-of-a-contract.rst | 10 ++++++++++
 vyper/cli/vyper_compile.py       |  6 +++++-
 vyper/venom/README.md            |  2 +-
 4 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/docs/compiling-a-contract.rst b/docs/compiling-a-contract.rst
index c2cd3ed22c..7132cff58d 100644
--- a/docs/compiling-a-contract.rst
+++ b/docs/compiling-a-contract.rst
@@ -31,7 +31,7 @@ Include the ``-f`` flag to specify which output formats to return. Use ``vyper -
 
 .. code:: shell
 
-    $ vyper -f abi,abi_python,bytecode,bytecode_runtime,blueprint_bytecode,interface,external_interface,ast,annotated_ast,integrity,ir,ir_json,ir_runtime,asm,opcodes,opcodes_runtime,source_map,source_map_runtime,archive,solc_json,method_identifiers,userdoc,devdoc,metadata,combined_json,layout yourFileName.vy
+    $ vyper -f abi,abi_python,bb,bb_runtime,bytecode,bytecode_runtime,blueprint_bytecode,cfg,cfg_runtime,interface,external_interface,ast,annotated_ast,integrity,ir,ir_json,ir_runtime,asm,opcodes,opcodes_runtime,source_map,source_map_runtime,archive,solc_json,method_identifiers,userdoc,devdoc,metadata,combined_json,layout yourFileName.vy
 
 .. note::
     The ``opcodes`` and ``opcodes_runtime`` output of the compiler has been returning incorrect opcodes since ``0.2.0`` due to a lack of 0 padding (patched via `PR 3735 <https://github.com/vyperlang/vyper/pull/3735>`_). If you rely on these functions for debugging, please use the latest patched versions.
@@ -134,6 +134,11 @@ In codesize optimized mode, the compiler will try hard to minimize codesize by
 * out-lining code, and
 * using more loops for data copies.
 
+Enabling Experimental Code Generation
+===========================
+
+When compiling, you can use the CLI flag ``--experimental-codegen`` or its alias ``--venom`` to activate the new `Venom IR <https://github.com/vyperlang/vyper/blob/master/vyper/venom/README.md>`_.
+Venom IR is inspired by LLVM IR and enables new advanced analysis and optimizations.
 
 .. _evm-version:
 
diff --git a/docs/structure-of-a-contract.rst b/docs/structure-of-a-contract.rst
index fc817cf4b6..7e599d677b 100644
--- a/docs/structure-of-a-contract.rst
+++ b/docs/structure-of-a-contract.rst
@@ -54,6 +54,16 @@ EVM Version
 
 The EVM version can be set with the ``evm-version`` pragma, which is documented in :ref:`evm-version`.
 
+Experimental Code Generation
+-----------------
+The new experimental code generation feature can be activated using the following directive:
+
+.. code-block:: vyper
+
+   #pragma experimental-codegen
+
+Alternatively, you can use the alias ``"venom"`` instead of ``"experimental-codegen"``  to enable this feature.
+
 Imports
 =======
 
diff --git a/vyper/cli/vyper_compile.py b/vyper/cli/vyper_compile.py
index fde35f781e..046cac2c0b 100755
--- a/vyper/cli/vyper_compile.py
+++ b/vyper/cli/vyper_compile.py
@@ -34,6 +34,8 @@
 layout             - Storage layout of a Vyper contract
 ast                - AST (not yet annotated) in JSON format
 annotated_ast      - Annotated AST in JSON format
+cfg                - Control flow graph of deployable bytecode
+cfg_runtime        - Control flow graph of runtime bytecode
 interface          - Vyper interface of a contract
 external_interface - External interface of a contract, used for outside contract calls
 opcodes            - List of opcodes as a string
@@ -41,6 +43,8 @@
 ir                 - Intermediate representation in list format
 ir_json            - Intermediate representation in JSON format
 ir_runtime         - Intermediate representation of runtime bytecode in list format
+bb                 - Basic blocks of Venom IR for deployable bytecode
+bb_runtime         - Basic blocks of Venom IR for runtime bytecode
 asm                - Output the EVM assembly of the deployable bytecode
 integrity          - Output the integrity hash of the source code
 archive            - Output the build as an archive file
@@ -177,7 +181,7 @@ def _parse_args(argv):
     parser.add_argument(
         "--experimental-codegen",
         "--venom",
-        help="The compiler use the new IR codegen. This is an experimental feature.",
+        help="The compiler uses the new IR codegen. This is an experimental feature.",
         action="store_true",
         dest="experimental_codegen",
     )
diff --git a/vyper/venom/README.md b/vyper/venom/README.md
index 4e4f5ca3d1..6f3b318c9b 100644
--- a/vyper/venom/README.md
+++ b/vyper/venom/README.md
@@ -193,7 +193,7 @@ An operand can be a label, a variable, or a literal.
 By convention, variables have a `%-` prefix, e.g. `%1` is a valid variable. However, the prefix is not required.
 
 ## Instructions
-To enable Venom IR in Vyper, use the `--experimental-codegen` flag. To view the Venom IR output, use `-f bb_runtime` for the runtime code, or `-f bb` to see the deploy code. To get a dot file (for use e.g. with `xdot -`), use `-f cfg` or `-f cfg_runtime`.
+To enable Venom IR in Vyper, use the `--experimental-codegen` CLI flag or its alias `--venom`, or the corresponding pragma statements (e.g. `#pragma experimental-codegen`). To view the Venom IR output, use `-f bb_runtime` for the runtime code, or `-f bb` to see the deploy code. To get a dot file (for use e.g. with `xdot -`), use `-f cfg` or `-f cfg_runtime`.
 
 Assembly can be inspected with `-f asm`, whereas an opcode view of the final bytecode can be seen with `-f opcodes` or `-f opcodes_runtime`, respectively.