a note about Symbol.typeSignature

No changes to behavior, just documenting internal workings of reflection
a bit more thoroughly, one step at a time.

1 files changed, 7 insertions, 0 deletions

diff --git a/src/reflect/scala/reflect/internal/Symbols.scala b/src/reflect/scala/reflect/internal/Symbols.scala
index e15b33e5d7..28d980bcfd 100644
--- a/src/reflect/scala/reflect/internal/Symbols.scala
+++ b/src/reflect/scala/reflect/internal/Symbols.scala
@@ -118,6 +118,13 @@ trait Symbols extends api.Symbols { self: SymbolTable =>
     def baseClasses                       = info.baseClasses
     def module                            = sourceModule
     def thisPrefix: Type                  = thisType
+
+    // automatic full initialization on access to info from reflection API is a double-edged sword
+    // on the one hand, it's convenient so that the users don't have to deal with initialization themselves before printing out stuff
+    // (e.g. printing out a method's signature without fully initializing it would result in <_>'s for parameters
+    // on the other hand, this strategy can potentially cause unexpected effects due to being inconsistent with compiler's behavior
+    // so far I think user convenience outweighs the scariness, but we need to keep the tradeoff in mind
+    // NOTE: if you end up removing the call to fullyInitializeSymbol, consider that it would affect both runtime reflection and macros
     def typeSignature: Type               = { fullyInitializeSymbol(this); info }
     def typeSignatureIn(site: Type): Type = { fullyInitializeSymbol(this); site memberInfo this }