From: LE Manh Cuong <cuong.manhle.vn@gmail.com>
Date: Fri, 3 May 2019 17:24:53 +0000 (+0700)
Subject: cmd/compile: clarify the difference between types.Sym and obj.LSym
X-Git-Tag: go1.13beta1~243
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=2d7cb295fdda94f3d62588b7bb01a4d8b445417a;p=gostls13.git

cmd/compile: clarify the difference between types.Sym and obj.LSym

Both types.Sym and obj.LSym have the field Name, and that field is
widely used in compiler source. It can lead to confusion that when to
use which one.

So, adding documentation for clarifying the difference between them,
eliminate the confusion, or at least, make the code which use them
clearer for the reader.

See https://github.com/golang/go/issues/31252#issuecomment-481929174

Change-Id: I31f7fc6e4de4cf68f67ab2e3a385a7f451c796f5
Reviewed-on: https://go-review.googlesource.com/c/go/+/175019
Reviewed-by: Keith Randall <khr@golang.org>
Reviewed-by: Matthew Dempsky <mdempsky@google.com>
---

diff --git a/src/cmd/compile/internal/gc/syntax.go b/src/cmd/compile/internal/gc/syntax.go
index 12bc9c3ae6..9f6646af44 100644
--- a/src/cmd/compile/internal/gc/syntax.go
+++ b/src/cmd/compile/internal/gc/syntax.go
@@ -280,7 +280,7 @@ func (n *Node) isMethodExpression() bool {
 	return n.Op == ONAME && n.Left != nil && n.Left.Op == OTYPE && n.Right != nil && n.Right.Op == ONAME
 }
 
-// funcname returns the name of the function n.
+// funcname returns the name (without the package) of the function n.
 func (n *Node) funcname() string {
 	if n == nil || n.Func == nil || n.Func.Nname == nil {
 		return "<nil>"
diff --git a/src/cmd/compile/internal/types/sym.go b/src/cmd/compile/internal/types/sym.go
index 13761c7615..2779c368a9 100644
--- a/src/cmd/compile/internal/types/sym.go
+++ b/src/cmd/compile/internal/types/sym.go
@@ -11,14 +11,20 @@ import (
 	"unicode/utf8"
 )
 
-// Sym represents an object name. Most commonly, this is a Go identifier naming
-// an object declared within a package, but Syms are also used to name internal
-// synthesized objects.
+// Sym represents an object name in a segmented (pkg, name) namespace.
+// Most commonly, this is a Go identifier naming an object declared within a package,
+// but Syms are also used to name internal synthesized objects.
 //
 // As an exception, field and method names that are exported use the Sym
 // associated with localpkg instead of the package that declared them. This
 // allows using Sym pointer equality to test for Go identifier uniqueness when
 // handling selector expressions.
+//
+// Ideally, Sym should be used for representing Go language constructs,
+// while cmd/internal/obj.LSym is used for representing emitted artifacts.
+//
+// NOTE: In practice, things can be messier than the description above
+// for various reasons (historical, convenience).
 type Sym struct {
 	Importdef *Pkg   // where imported definition was found
 	Linkname  string // link name
diff --git a/src/cmd/internal/obj/link.go b/src/cmd/internal/obj/link.go
index 3ea29a87a9..66748b25d2 100644
--- a/src/cmd/internal/obj/link.go
+++ b/src/cmd/internal/obj/link.go
@@ -377,6 +377,7 @@ const (
 )
 
 // An LSym is the sort of symbol that is written to an object file.
+// It represents Go symbols in a flat pkg+"."+name namespace.
 type LSym struct {
 	Name string
 	Type objabi.SymKind