From fc22cb6fe202aef13316bea1e19734c8c6d68bed Mon Sep 17 00:00:00 2001
From: Jeremy Nimmer <jeremy.nimmer@tri.global>
Date: Tue, 21 Mar 2023 13:12:15 -0700
Subject: [PATCH] [doc] Provide an inventory of our environment variables

---
 doc/doxygen_cxx/doxygen.h | 32 ++++++++++++++++++++++++++++++++
 solvers/gurobi_solver.h   |  4 ++++
 2 files changed, 36 insertions(+)

diff --git a/doc/doxygen_cxx/doxygen.h b/doc/doxygen_cxx/doxygen.h
index 652d0b7af43b..b34263ed419b 100644
--- a/doc/doxygen_cxx/doxygen.h
+++ b/doc/doxygen_cxx/doxygen.h
@@ -208,4 +208,36 @@ namespace solvers {
  @}
 */
 
+/** @addtogroup technical_notes
+
+ @{
+
+ @defgroup environment_variables Environment Variables
+
+ This section provides an inventory of environment variables relevant to Drake.
+
+ - <b>\ref drake::common::FindResource() "DRAKE_RESOURCE_ROOT"</b>
+ - <b>\ref drake::solvers::GurobiSolver "GRB_LICENSE_FILE"</b> (see also 
+   <a href="https://support.gurobi.com/hc/en-us/articles/360013417211-Where-do-I-place-the-Gurobi-license-file-gurobi-lic-">upstream documentation</a>)
+ - <b>\ref drake::solvers::GurobiSolver "GUROBI_NUM_THREADS"</b>
+ - <b>HOME</b>
+ - <b>\ref drake::solvers::MosekSolver "MOSEKLM_LICENSE_FILE"</b> (see also
+   <a href="https://docs.mosek.com/latest/licensing/client-setup.html">upstream documentation</a>)
+ - <b>\ref drake::multibody::PackageMap::PopulateFromRosPackagePath() "ROS_PACKAGE_PATH"</b> (see also
+   <a href="http://wiki.ros.org/ROS/EnvironmentVariables">upstream documentation)</a>
+ - <b>RUNFILES_DIR</b> (see
+   <a href="https://github.com/bazelbuild/bazel/blob/6.1.1/tools/python/runfiles/runfiles.py#L77">upstream documentation)</a>
+ - <b>RUNFILES_MANIFEST_FILE</b> (see
+   <a href="https://github.com/bazelbuild/bazel/blob/6.1.1/tools/python/runfiles/runfiles.py#L77">upstream documentation)</a>
+ - <b>TEST_SRCDIR</b> (see
+   <a href="https://bazel.build/reference/test-encyclopedia#initial-conditions">upstream documentation</a>)
+ - <b>\ref drake::temp_directory() "TEST_TMPDIR"</b>
+ - <b>\ref drake::temp_directory() "TMPDIR"</b>
+ - <b>USER</b>
+ - <b>XDG_CACHE_HOME</b> (see
+   <a href="https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html">upstream documentation</a>)
+
+ @}
+*/
+
 } // namespace drake
diff --git a/solvers/gurobi_solver.h b/solvers/gurobi_solver.h
index 3963585dace4..cc8a9340e768 100644
--- a/solvers/gurobi_solver.h
+++ b/solvers/gurobi_solver.h
@@ -60,6 +60,10 @@ struct GurobiSolverDetails {
 ///    for more details. Often this method is called together with
 ///    setting GRBwrite to "FILENAME.ilp" to write IIS to a file with extension
 ///    "ilp". Default is not to compute IIS.
+///
+/// If the "Threads" integer solver option has not been set by the user, then
+/// %GurobiSolver uses environment variable GUROBI_NUM_THREADS (if set) as a
+/// default value for "Threads".
 class GurobiSolver final : public SolverBase {
  public:
   DRAKE_NO_COPY_NO_MOVE_NO_ASSIGN(GurobiSolver)