x/pkgsite: show exported fields promoted from unexported anonymous fields

[ugorji]

Within my code, I have the following structure.

type common struct {
    Option1 bool
}

func (c *common) Method1() {
}

type A struct {
    OptionA int
    common
}

type B struct {
    OptionB int
    common
}

I want godoc to show that type A and type B have field Option1 available, and Method1 in
their method sets.

However, godoc would not show Option1, because common is not exported. It however show
Method1 (the full method set).

The only current workaround is to export common (which really is an internal
implementation detail), or duplicate the functionality across all types that share it. 

TO fix, godoc should show these promoted fields got from unexported anonymous fields. 

For example, godoc output for A could look like:

type A struct {
    OptionA int
    // contains filtered or unexported fields
    // Available from unexported anonymous fields
    Option1 bool
}


Which version are you using?  (run 'go version')
go version devel +47b2b07a837f Fri Oct 11 16:39:40 2013 -0700 linux/amd64

Please provide any additional information below.

[rsc]

Comment 1:

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

Status changed to Accepted.

[rsc]

Comment 2:

Labels changed: added go1.3maybe.

[rsc]

Comment 3:

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

[rsc]

Comment 4:

Labels changed: added repo-tools.

[alecthegeek]

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.

[agnivade]

@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.

[agnivade]

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

[gopherbot]

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

[griesemer]

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

[agnivade]

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?

[zigo101]

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

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

[dsnet]

@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()

[zigo101]

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

[ddrake17]

+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

[gonutz]

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

[ThisGuyCodes]

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.

[zigo101]

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

[betamos]

I'm in favor. From a principled POV the primary goal of documentation should be to display everything that a user can access and do, i.e. how they can interact with the module. Anything accessible according to the visibility rules of the language should appear in the docs.

Now, from a direct use case, embeddings are particularly important because they affect which interfaces are implemented. Consider this use-case:

type netConn net.Conn

type Conn struct {
    netConn // We don't allow direct access to the inner net.Conn to prevent accidental misuse
    br *bufio.Reader
}

func (c *Conn) Read(p []byte) (int, error) {
    // Override to read from the bufio.Reader, common for wire protocols
}

// Forward the rest (7 methods) to the inner conn

Crucially, users need to know that *Conn implements net.Conn, but it's impossible to tell from the docs:

type Conn struct {
    // Has unexported fields.
}

func (c *Conn) Read(p []byte) (int, error)

[FiloSottile]

This caught me by surprise, and can create compatibility issues: when preparing to publish a package, and especially when tagging v1.0.0, I always make sure I am happy with the exposed API. However, due to this, I exposed fields I did not meant to expose without noticing, and removing them would technically be a backwards compatibility issue.

At least, we should change the // contains filtered or unexported fields comment to flag the presence of exported embedded fields.