Comment 1:

Labels changed: added priority-later, removed priority-triage.

Status changed to Accepted.

Comment 2:

Labels changed: added go1.3maybe.

Comment 3:

Labels changed: added release-none, removed go1.3maybe.

Comment 4:

Labels changed: added repo-tools.

I have what I think is the same problem. Public receiver methods (on a hidden type) do not have their document strings displayed. Consider this code

//Package showme demonstrates that public receivers on a hidden type are not documented
package showme

type hiddenType struct {
  i int
  s string
}
type PublicType struct {
  i int
  s string
}

// PublicFA should be documented
func (hiddenType) PublicFA(){
  //do something boring
}

// PublicFB will be documented
func (PublicType) PublicFB(){
  //do something boring
}

Method PublicFA is not documented when I run godoc.

@alecthegeek - Your issue is different. PublicFA should not be documented because it is attached to hiddenType which is not exported. You need to expose hiddenType if you want PublicFA to be visible.

This issue is about displaying exported fields from embedded fields in a type which itself is exported.

Interesting thing to note is if common is exported, Method1() stops showing up. Probably related to #6127.

Change https://golang.org/cl/131176 mentions this issue: go/doc: show exported fields of embedded structs

Before we write any more code for this, we need to decide if and what we should do about this.

Copying over @dsnet's thoughts from the CL for completeness -

I don't think we should do this. I have following concerns:

• Uplifting exported fields from embedded unexported structs to the parent struct lies to the user about the true nature of the type. Now godoc claims that the parent has a field of some given name, but instantiating the struct as a literal does not match what godoc says. For example (from your testdata), U1 claims to have a field F1, so I would expect to be able to write a literal of the form U1{F1: "string"}, but this is not valid and my code fails to build.
• Sometimes people deliberately embed an unexported type precisely because they want to hide the exported fields.
• This bakes in more understanding of type information into godoc that fundamentally belongs in go/types. When do we stop giving more understanding of types to godoc?

I'm some surprised that the following cmd doesn't work:

$ go doc *sync.Cond
doc: invalid identifier "*sync"
exit status 1

@go101, what you're describing is orthogonal to this issue. The go doc tool does not know about pointers. Instead, you should do:

$ go doc sync.Cond
type Cond struct {

	// L is held while observing or changing the condition
	L Locker

	// Has unexported fields.
}
    Cond implements a condition variable, a rendezvous point for goroutines
    waiting for or announcing the occurrence of an event.

    Each Cond has an associated Locker L (often a *Mutex or *RWMutex), which
    must be held when changing the condition and when calling the Wait method.

    A Cond must not be copied after first use.


func NewCond(l Locker) *Cond
func (c *Cond) Broadcast()
func (c *Cond) Signal()

There are more cases of exported methods/fields are not listed by doc cmd and godoc webpages.

1. the exported methods and fields of exported variables of unexported types.
2. the exported methods and fields of results of unexported types of exported functions.
3. the exported methods and fields of the exported alias of unexported types

+1 for allowing documentation of embedded struct's exported fields. In response to @dsnet and @agnivade said:

• It's true that there are some differences and so perhaps the fields should not be given the exact same doc status as regular exported fields, but I think there is still value in showing the fields since users can access them. The example in the issue report shows one way of documenting them differently.
• One issue pointed out was forming a struct literal but a clear differentiation in comment would show the user they can't create it the normal way.
• Also you can still access the embedded fields in other ways that are exactly the same as if they were fields of the exported struct itself (e.g. using the example code in the issue report, if B.Option == false ). Although you can access these fields and use them there isn't a good way to tell this from reading the docs since they aren't shown at all.
• If package writers don't want people accessing exported fields then there are multiple ways to hide them like unexporting them, or embedding the struct with a named unexported field.

I think the proposed doc solution in the report was good and would differentiate things enough so users were not confused

I am surprised that throughout this thread it seems people are unsure whether to do anything about it. Labels like priority-later and comments like we need to decide if and what we should do about this suggest that this is not an important issue.

For me it is. I want to go look at the package site and see what functions I can call on my objects but it does not show them to me. I am glad that there are people working on this and I am not entitled to tell you what to spend your time on, but I would like to bump this up in priority in people's minds since it is a major issue for me at the moment. I rely on the package site quite a lot since my IDE's auto-completion broke (when modules were introduced) and for the most part it works. But this is really a pain point for me and I would be very happy to see this issue fixed.

For reference, I was the one to open issue #48722

This issue creates situations where one reads code that uses exported fields that are not present in documentation.

Example, the usage section of the documentation for https://github.com/andreykaipov/goobs shows the following example code:

On line 16 you see this:

version, err := client.General.GetVersion()

but the documentation for *goobs.Client looks like this:

Despite .General being an available field on goobs.Client, it does not show in the documentation.

While I accept there are multiple possible solutions here, I have difficulty understanding how this can be seen as anything but obviously incorrect.

You can try Golds, which lists all promoted fields and methods.