📝 Improve documentation

Author: Rubilmax

README.md

@@ -2,8 +2,20 @@
 
 Easily generate & compare gas reports automatically generated by Foundry on each of your Pull Requests!
 
+## How it works
+
+Everytime somebody opens a Pull Request, the action expects [Foundry](https://github.com/foundry-rs/foundry) `forge` to run a test suite, generating a gas report to a temporary file (named `gasreport.ansi` by default).
+
+Once generated, the action will fetch the comparative gas report stored as an artifact from previous runs; parse & compare them, storing the results in the action's outputs as shell and as markdown.
+
+You can then do whatever you want with the results!
+
+> **Our recommandation:** Automatically submit a sticky comment displaying the gas diff!
+
 ## Live Example
 
+---
+
 ### Changes to gas costs
 
 #### 🧾 Summary
@@ -26,6 +38,8 @@ Easily generate & compare gas reports automatically generated by Foundry on each
 
 </details>
 
+---
+
 ## Getting started
 
 ### Automatically generate a gas report diff on every PR
@@ -42,15 +56,24 @@ on:
   pull_request:
     # Optionally configure to run only for specific files. For example:
     # paths:
-    # - "src/**"
+    # - src/**
 
 jobs:
   compare_gas_reports:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
 
-      # Add any build steps here. For example:
+      - name: Install Foundry
+        uses: onbjerg/foundry-toolchain@v1
+        with:
+          version: nightly
+
+      - name: Install Dependencies
+        run: forge install
+
+      # Add any step generating a gas report to a temporary file named gasreport.ansi (can be changed)
+      # For example:
       - run: forge test --gas-report > gasreport.ansi
 
       - name: Compare gas reports
@@ -68,6 +91,10 @@ jobs:
           message: ${{ steps.gas_diff.outputs.markdown }}
 ```
 
+> :information_source: **An error will appear at first run!**<br/>
+> 🔴 <em>**Error:** No workflow run found with an artifact named "main.gasreport.ansi"</em><br/>
+> As the action is expecting a comparative file stored on the base branch and cannot find it (because the action never ran on the target branch and thus has never uploaded any gas report)
+
 ## Options
 
 ### `workflowId` _{string}_ (required)
@@ -78,7 +105,7 @@ thus it should correspond to the ID of the workflow this action is defined in: `
 
 ### `token` _{string}_
 
-The github token allowing the action to upload and download gas reports generated by foundry.
+The github token allowing the action to upload and download gas reports generated by foundry. You should not need to customize this, as the action already has access to the default Github Action token.
 
 _Defaults to: `${{ github.token }}`_
 
@@ -121,6 +148,14 @@ This allows to only display gas diff of specific contracts.
 
 _No default assigned: optional opt-in_
 
+## ⚠️ Known limitations
+
+> **Library gas reports**<br/>
+> Forge does not generate library gas reports. You need to wrap their usage in a contract calling the library to be able to compare gas costs of calling the library.
+
+> **Average gas cost estimation**<br/>
+> Average & median gas costs for each function is estimated based on the test suite, which means they are easily impacted by small changes in the tests. We recommend using a separate, specific test suite, rarily updated, designed to perform accurate gas estimations.
+
 ## Status
 
 ![Status: Experimental](https://img.shields.io/badge/Status-Experimental-blue)