nix: Document the implementation of default.nix

Author: ibbem

default.nix

@@ -33,6 +33,9 @@ pkgs.stdenvNoCC.mkDerivation rec {
     jekyll-theme-cayman
   ]));
 
+  # Maven needs to download necessary dependencies which is impure because it
+  # requires network access. Hence, we download all dependencies as a
+  # fixed-output derivation. This also serves as a nice cache.
   mavenRepo = pkgs.stdenv.mkDerivation {
     pname = "${pname}-mavenRepo";
     inherit version;
@@ -67,6 +70,10 @@ pkgs.stdenvNoCC.mkDerivation rec {
     outputHash = dependenciesHash;
   };
 
+  # - `out` contains jars, an executable wrapper and optionally documentation
+  #   (see `buildGitHubPages`)
+  # - `maven` contains a local maven repository with DiffDetective and all its
+  #   build-time and run-time dependencies.
   outputs = ["out" "maven"];
 
   jre-minimal = pkgs.callPackage (import "${sources.nixpkgs}/pkgs/development/compilers/openjdk/jre.nix") {
@@ -108,12 +115,14 @@ pkgs.stdenvNoCC.mkDerivation rec {
   installPhase = ''
     runHook preInstall
 
+    # install jars in "$out"
     install -Dm644 "target/diffdetective-${version}.jar" "$out/share/java/DiffDetective.jar"
     local jar="$out/share/java/DiffDetective/DiffDetective.jar"
     install -Dm644 "target/diffdetective-${version}-jar-with-dependencies.jar" "$jar"
     makeWrapper "${jre-minimal}/bin/java" "$out/bin/DiffDetective" --add-flags "-cp \"$jar\"" \
       --prefix PATH : "${pkgs.graphviz}/bin"
 
+    # install documentation in "$out"
     ${
       if buildGitHubPages
       then ''
@@ -123,6 +132,7 @@ pkgs.stdenvNoCC.mkDerivation rec {
       else ""
     }
 
+    # install DiffDetective in "$maven" by creating a copy of "$mavenRepo" as base
     cp -r "$mavenRepo" "$maven"
     chmod u+w -R "$maven"
     mvn --offline -Dmaven.repo.local="$maven" -Dmaven.test.skip=true install