doc: Improve m_best_header documentation

mzumsande · mzumsande · commit f6b782f3aad4 · 2025-06-06T11:23:44.000-04:00
diff --git a/src/validation.h b/src/validation.h
@@ -1038,7 +1038,10 @@ class ChainstateManager
     }
 
 
-    /** Best header we've seen so far (used for getheaders queries' starting points). */
+    /** Best header we've seen so far for which the block is not known to be invalid
+        (used, among others, for getheaders queries' starting points).
+        In case of multiple best headers with the same work, it could point to any
+        because CBlockIndexWorkComparator tiebreaker rules are not applied. */
     CBlockIndex* m_best_header GUARDED_BY(::cs_main){nullptr};
 
     //! The total number of bytes available for us to use across all in-memory

Original file line number	Diff line number	Diff line change
`@@ -1038,7 +1038,10 @@ class ChainstateManager`
`1038`	`1038`	`}`
`1039`	`1039`
`1040`	`1040`
`1041`		`- /** Best header we've seen so far (used for getheaders queries' starting points). */`
	`1041`	`+ /** Best header we've seen so far for which the block is not known to be invalid`
	`1042`	`+ (used, among others, for getheaders queries' starting points).`
	`1043`	`+ In case of multiple best headers with the same work, it could point to any`
	`1044`	`+ because CBlockIndexWorkComparator tiebreaker rules are not applied. */`
`1042`	`1045`	`CBlockIndex* m_best_header GUARDED_BY(::cs_main){nullptr};`
`1043`	`1046`
`1044`	`1047`	`//! The total number of bytes available for us to use across all in-memory`