First of all, we don't use the issue tracker for questions. Also, please, refrain from shouting questions by ending them in '???????...'; the design is not as insane as the '?'s imply... Thanks.

Regarding the documentation:

NewTypeName creates a new TypeName as the signature implies. That object, TypeName, represents a name for a named or alias type. That's in fact documented with TypeName, 5 lines above. Thus, the typ argument may or may not be the underlying type, and hence it's not called underlying, exactly because that would be confusing.

NewNamed creates a new NamedType, where NamedType is the historical name we used for what is now called a defined type in the spec. For backward-compatibility we couldn't change those names. A named (or defined) type has an underlying type, which is the type on which the new named type is based.

A NamedType points to its TypeName which points back to its NamedType. If you read the 8 lines of code in NewNamed you will see how that connection is established.

The go/types API is not really documented for general consumption (it would fill reams of pages); it does require a bit of digging and reading the code.

I see what you're saying. The many ?'s threw me off; I didn't see that they meant to be a place holder; sorry about that.

I understood it's a documentation issue, and so I left it open because of that. (Just saying that it's unclear from documentation what/which type you need to provide to NewTypeName would probably be enough; especially because that method actually is missing a doc string. It would have been pretty clear.)

But to your question: If you look at NewNamed, as I have alluded to in my prior comment, you will see that NewNamed actually connects back from the provided TypeName to the Named type, if necessary. So you can call NewTypeName with a nil type and then provide it to NewNamed which will then connect them.

Btw., I didn't say go/types isn't meant for general consumption; I said it's not documented for general consumption.

The primary use case for go/types is to produce type information for a given package, which then can be queried. The primary reason why methods and functions for constructing go/types data structures are exposed is so that we can write importers (which are in different packages). When we wrote it we (Alan Donovan and I) agonized how to get around this, well knowing that it would lead to endless troubles down the road exactly because proper use of these constructors requires intimate knowledge of how type graphs are constructed; something that we didn't meant to expose for general consumption. Hence the missing documentation.

Change https://golang.org/cl/75595 mentions this issue: go/types: add missing documentation to Object factory functions

For the record: I'm glad that these functions are exported and am using them to implement a custom, database-backed importer.

Just saying that it's unclear from documentation what/which type you need to provide to NewTypeName would probably be enough; especially because that method actually is missing a doc string. It would have been pretty clear.

Makes sense.

If you look at NewNamed, as I have alluded to in my prior comment, you will see that NewNamed actually connects back from the provided TypeName to the Named type, if necessary. So you can call NewTypeName with a nil type and then provide it to NewNamed which will then connect them.

Makes sense. Sorry, I was on my phone and didn't have the source in front of me to check out.

Btw., I didn't say go/types isn't meant for general consumption; I said it's not documented for general consumption.

My mistake. I see what you mean, but in my mind, if a package is meant for general consumption, it should be documented as such.

well knowing that it would lead to endless troubles down the road exactly because proper use of these constructors requires intimate knowledge of how type graphs are constructed; something that we didn't meant to expose for general consumption. Hence the missing documentation.

If the constructors aren't meant to be used, it would be clearer if their documentation said so. Or perhaps it could say they're deprecated. Leaving them out there and not documented can be frustrating to newcomers who don't know.

There don't seem to be that many complications, though. Would the additional documentation be that much more? This documentation issue, for example, could be explained with two additional lines in the NewTypeName and NewNamed documentation:

// NewTypeName [...]. If the type name will be used to make a named type, the type
// should be nil, and NewNamed will set it.
func NewTypeName(pos token.Pos, pkg *Package, name string, typ Type) *TypeName

// NewNamed [...]. It sets the type name's type to the named type.
func NewNamed(obj *TypeName, underlying Type, methods []*Func) *Named

...and I just saw the associated changelist! Thank you. :)

@dominikh Agreed.