From 673446c1dd66e04c127623316085bb7a9dd988f5 Mon Sep 17 00:00:00 2001
From: Jerome Dockes <jerome@dockes.org>
Date: Thu, 11 Jul 2024 17:19:14 +0200
Subject: [PATCH] more comments

---
 skrub/_reporting/_data/templates/base.css      | 18 +++++++++++++-----
 .../_data/templates/inline-report.css          |  5 +++++
 2 files changed, 18 insertions(+), 5 deletions(-)

diff --git a/skrub/_reporting/_data/templates/base.css b/skrub/_reporting/_data/templates/base.css
index 78a0d8db3..02d4abb31 100644
--- a/skrub/_reporting/_data/templates/base.css
+++ b/skrub/_reporting/_data/templates/base.css
@@ -9,11 +9,8 @@
     --huge: 1.5rem;
     --max-content-width: 45rem;
     --radius: 0.25rem;
-    --yellowish: #ffffaa;
 
-    --lightviolet: #f3eafa;
-    --mediumviolet: #e6d6f5;
-    --darkviolet: #dac1f0;
+    --yellowish: #ffffaa;
 
     --lightgreen: #eafaea;
     --mediumgreen: #d6f5d6;
@@ -24,7 +21,7 @@
     --mediumg: #d0d0d0;
     --lightg: #f0f0f0;
 
-    /* copied from github */
+    /* the font stack is copied from github */
     --fontStack-monospace: ui-monospace, SFMono-Regular, SF Mono, Menlo, Consolas, Liberation Mono, monospace;
     --fontStack-sansSerif: -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji";
 }
@@ -35,6 +32,11 @@
     -webkit-text-size-adjust: 100%;
 }
 
+/* The report is in a shadow DOM so outside selectors don't reach it but properties */
+/* can still be inherited from a parent element. We make sure it has black text on */
+/* a white background otherwise eg a dark mode in the page could make parts of it */
+/* unreadable. */
+
 #report {
     background: white;
     color: black;
@@ -73,6 +75,9 @@ code, pre {
     white-space: nowrap;
 }
 
+/* Align the items of definition lists, used to show the columns metadata (number */
+/* of null values, mean, etc) */
+
 dl {
     display: grid;
     grid-template-columns: max-content auto;
@@ -222,6 +227,9 @@ dd {
     color: red;
 }
 
+/* .if-else provides a group of 2 elements that we can toggle to decide which is shown. */
+/* Used for example to show columns OR a message saying that none match the filter */
+
 .if-else[data-predicate="false"] > :first-child{
     display: none;
 }
diff --git a/skrub/_reporting/_data/templates/inline-report.css b/skrub/_reporting/_data/templates/inline-report.css
index 5d6d0ddc5..633cfdbb5 100644
--- a/skrub/_reporting/_data/templates/inline-report.css
+++ b/skrub/_reporting/_data/templates/inline-report.css
@@ -1,3 +1,8 @@
+/* Add a horizontal line below the report to separate it from surrounding content. */
+/* This only gets included when generating an html snippet, not a full page, */
+/* because it is unnecessary and looks worse when the report is the only content on */
+/* the page. */
+
 .tab[data-is-displayed] {
     border-bottom: 1px solid var(--mediumg);
 }