diff --git a/forge.go b/forge.go
index bcc9770..6e20128 100644
--- a/forge.go
+++ b/forge.go
@@ -61,6 +61,22 @@
 //      An identifier which main contain periods which starts with a period, the references
 //      are resolved from the settings current section (e.g. .value, .sub_section.value)
 //
+// Note about references.
+// References are resolved during parsing not access (they do not act as pointers... today).
+// Meaning that if I have the following config:
+//   setting = "value";
+//   ref_to_setting = setting;
+//
+// During parsing when I get to `ref_to_setting` it will be resolved immediately and it's value will
+// be set to `"value"`.
+//
+// This config example, however, will raise a parsing error since it cannot resolve the reference:
+//   ref_to_setting = setting;
+//   setting = "value";
+//
+// Since `setting` does not exist yet.
+// This is mostly due to the naive implementation of references today. How they work may change in
+// future versions or they may disappear entirely.
 //
 // Directives
 //  * Comment: