From 8a5e2b19a8c85e6127984f214c43e121f5654b29 Mon Sep 17 00:00:00 2001
From: Yuval Tassa <tassa@google.com>
Date: Mon, 6 Nov 2023 07:27:40 -0800
Subject: [PATCH] Improve `mjContact` documentation. Fixes #1136

PiperOrigin-RevId: 579836970
Change-Id: Ife8dd73eecdbdaacecc1e48460cf6efcf4f7b487
---
 doc/includes/references.h | 6 +++---
 include/mujoco/mjdata.h   | 6 +++---
 introspect/structs.py     | 6 +++---
 3 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/doc/includes/references.h b/doc/includes/references.h
index 5dc192b4..7e7e7db7 100644
--- a/doc/includes/references.h
+++ b/doc/includes/references.h
@@ -84,7 +84,7 @@ struct mjContact_ {                // result of collision detection functions
   // contact parameters set by near-phase collision function
   mjtNum  dist;                    // distance between nearest points; neg: penetration
   mjtNum  pos[3];                  // position of contact point: midpoint between geoms
-  mjtNum  frame[9];                // normal is in [0-2]
+  mjtNum  frame[9];                // normal is in [0-2], points from geom[0] to geom[1]
 
   // contact parameters set by mj_collideGeoms
   mjtNum  includemargin;           // include if dist<includemargin=margin-gap
@@ -99,8 +99,8 @@ struct mjContact_ {                // result of collision detection functions
 
   // contact descriptors set by mj_collideXXX
   int     dim;                     // contact space dimensionality: 1, 3, 4 or 6
-  int     geom1;                   // id of geom 1
-  int     geom2;                   // id of geom 2
+  int     geom1;                   // id of geom 1; deprecated, use geom[0]
+  int     geom2;                   // id of geom 2; deprecated, use geom[1]
   int     geom[2];                 // geom ids; -1 for flex
   int     flex[2];                 // flex ids; -1 for geom
   int     elem[2];                 // element ids; -1 for geom or flex vertex
diff --git a/include/mujoco/mjdata.h b/include/mujoco/mjdata.h
index 6475647c..a3609b8b 100644
--- a/include/mujoco/mjdata.h
+++ b/include/mujoco/mjdata.h
@@ -100,7 +100,7 @@ struct mjContact_ {                // result of collision detection functions
   // contact parameters set by near-phase collision function
   mjtNum  dist;                    // distance between nearest points; neg: penetration
   mjtNum  pos[3];                  // position of contact point: midpoint between geoms
-  mjtNum  frame[9];                // normal is in [0-2]
+  mjtNum  frame[9];                // normal is in [0-2], points from geom[0] to geom[1]
 
   // contact parameters set by mj_collideGeoms
   mjtNum  includemargin;           // include if dist<includemargin=margin-gap
@@ -115,8 +115,8 @@ struct mjContact_ {                // result of collision detection functions
 
   // contact descriptors set by mj_collideXXX
   int     dim;                     // contact space dimensionality: 1, 3, 4 or 6
-  int     geom1;                   // id of geom 1
-  int     geom2;                   // id of geom 2
+  int     geom1;                   // id of geom 1; deprecated, use geom[0]
+  int     geom2;                   // id of geom 2; deprecated, use geom[1]
   int     geom[2];                 // geom ids; -1 for flex
   int     flex[2];                 // flex ids; -1 for geom
   int     elem[2];                 // element ids; -1 for geom or flex vertex
diff --git a/introspect/structs.py b/introspect/structs.py
index e1bae540..37c6d410 100644
--- a/introspect/structs.py
+++ b/introspect/structs.py
@@ -3871,7 +3871,7 @@ STRUCTS: Mapping[str, StructDecl] = dict([
                      inner_type=ValueType(name='mjtNum'),
                      extents=(9,),
                  ),
-                 doc='normal is in [0-2]',
+                 doc='normal is in [0-2], points from geom[0] to geom[1]',
              ),
              StructFieldDecl(
                  name='includemargin',
@@ -3931,12 +3931,12 @@ STRUCTS: Mapping[str, StructDecl] = dict([
              StructFieldDecl(
                  name='geom1',
                  type=ValueType(name='int'),
-                 doc='id of geom 1',
+                 doc='id of geom 1; deprecated, use geom[0]',
              ),
              StructFieldDecl(
                  name='geom2',
                  type=ValueType(name='int'),
-                 doc='id of geom 2',
+                 doc='id of geom 2; deprecated, use geom[1]',
              ),
              StructFieldDecl(
                  name='geom',