From 6b2691d7ce0ebfadf750a29a2733fbaffec03d5f Mon Sep 17 00:00:00 2001
From: Thiago Kenji Okada <thiagokokada@gmail.com>
Date: Sat, 16 Apr 2022 13:33:19 +0100
Subject: [PATCH] graalvmXX-ce: add documentation to mkGraal function

---
 .../graalvm/community-edition/default.nix     |  2 --
 .../graalvm/community-edition/mkGraal.nix     | 31 +++++++++++++++++--
 2 files changed, 29 insertions(+), 4 deletions(-)

diff --git a/pkgs/development/compilers/graalvm/community-edition/default.nix b/pkgs/development/compilers/graalvm/community-edition/default.nix
index c50b9e49f55a..167aaa95c5ff 100644
--- a/pkgs/development/compilers/graalvm/community-edition/default.nix
+++ b/pkgs/development/compilers/graalvm/community-edition/default.nix
@@ -49,7 +49,6 @@ in
     };
     defaultVersion = graalvm11-ce-release-version;
     javaVersion = "11";
-    platforms = builtins.attrNames config;
   };
 
   graalvm17-ce = mkGraal rec {
@@ -74,6 +73,5 @@ in
     };
     defaultVersion = graalvm17-ce-release-version;
     javaVersion = "17";
-    platforms = builtins.attrNames config;
   };
 }
diff --git a/pkgs/development/compilers/graalvm/community-edition/mkGraal.nix b/pkgs/development/compilers/graalvm/community-edition/mkGraal.nix
index 768ad1fbaa17..77f0fa9b7dc5 100644
--- a/pkgs/development/compilers/graalvm/community-edition/mkGraal.nix
+++ b/pkgs/development/compilers/graalvm/community-edition/mkGraal.nix
@@ -1,9 +1,36 @@
-{ config
+{
+  # An attrset describing each platform configuration. All values are extract
+  # from the GraalVM releases available on
+  # https://github.com/graalvm/graalvm-ce-builds/releases
+  # Example:
+  # config = {
+  #   x86_64-linux = {
+  #     # List of products that will be included in the GraalVM derivation
+  #     # See `with{NativeImage,Ruby,Python,WASM,*}Svm` variables for the
+  #     # available values
+  #     products = [ "graalvm-ce" "native-image-installable-svm" ];
+  #     # GraalVM arch, not to be confused with the nix platform
+  #     arch = "linux-amd64";
+  #     # GraalVM version
+  #     version = "22.0.0.2";
+  #   };
+  # }
+  config
+  # GraalVM version that will be used unless overriden by `config.<platform>.version`
 , defaultVersion
+  # Java version used by GraalVM
 , javaVersion
-, platforms
+  # Platforms were GraalVM will be allowed to build (i.e. `meta.platforms`)
+, platforms ? builtins.attrNames config
+  # If set to true, update script will (re-)generate the sources file even if
+  # there are no updates available
 , forceUpdate ? false
+  # Path for the sources file that will be used
+  # See `update.nix` file for a description on how this file works
 , sourcesPath ? ./. + "/graalvm${javaVersion}-ce-sources.json"
+  # Use musl instead of glibc to allow true static builds in GraalVM's
+  # Native Image (i.e.: `--static --libc=musl`). This will cause glibc builds
+  # to fail, so it should be used with care
 , useMusl ? false
 }: