From 3da61fa4274b370dc2c72ce8b7bdbbfeb836110a Mon Sep 17 00:00:00 2001
From: Vytautas Astrauskas <vastrauskas@gmail.com>
Date: Mon, 18 May 2020 16:39:19 +0200
Subject: [PATCH] Add comments explaining the declare_id macro.

---
 src/sync.rs | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/src/sync.rs b/src/sync.rs
index e05d111cb28..7957faeb7e3 100644
--- a/src/sync.rs
+++ b/src/sync.rs
@@ -6,6 +6,10 @@ use rustc_index::vec::{Idx, IndexVec};
 
 use crate::*;
 
+/// We cannot use the `newtype_index!` macro because we have to use 0 as a
+/// sentinel value meaning that the identifier is not assigned. This is because
+/// the pthreads static initializers initialize memory with zeros (see the
+/// `src/shims/sync.rs` file).
 macro_rules! declare_id {
     ($name: ident) => {
         /// 0 is used to indicate that the id was not yet assigned and,
@@ -22,9 +26,13 @@ macro_rules! declare_id {
 
         impl Idx for $name {
             fn new(idx: usize) -> Self {
+                // We use 0 as a sentinel value (see the comment above) and,
+                // therefore, need to shift by one when converting from an index
+                // into a vector.
                 $name(NonZeroU32::new(u32::try_from(idx).unwrap() + 1).unwrap())
             }
             fn index(self) -> usize {
+                // See the comment in `Self::new`.
                 usize::try_from(self.0.get() - 1).unwrap()
             }
         }