What does it mean if a field is "filtered" in Go?

Question

In the Go documentation a type often shows only the exported fields. For example, the time.Timer documentation (https://golang.org/pkg/time/#Timer) shows the following:

type Timer

The Timer type represents a single event. When the Timer expires, the current time will be sent on C, unless the Timer was created by AfterFunc. A Timer must be created with NewTimer or AfterFunc.

type Timer struct {
     C <-chan Time
     // contains filtered or unexported fields
}

Go capitilizes to differentiate exported vs unexported fields, so this is clear. However, what does it mean (for example in the context of the comment above) to contain "filtered" fields?

Jeffreyjeffreys

Nothing. It just means it is not displayed in the output of go doc which is normal for unexported (read "private") fields. – Krell

In theory godoc could apply different filters. – Krell

That comment is produced by the go/printer code based on the AST passed to it. Some of the AST nodes have a field that flags them as incomplete and this field is used by the printer to decide whether or not to print that comment. However the printer has no way of knowing the rules and reasons for why that field was set to true or false and so by convention it is assumend it was done by a filter, the most common one being exportFilter, hence the language. – Bump

The "Incomplete" field is exported and can be set to true/false by anything that has access to the AST. You could walk the AST yourself setting each Incomplete field to true while leaving the nodes intact and then passing the AST to the printer which would then produce structs with all their fields, exported and unexported, and also that comment. – Bump

Godoc filters the AST with ast.FileExports which by default removes only unexported nodes, and then passes the AST to the printer. So in the case of Godoc the "filtered" in that comment is synonymous with "unexported". – Bump

@mkopriva: this would make a good answer. Why don't you post it as an answer? [FWIW it also matches the source code research I did after pondering about this question] – Roster

@EliBendersky i've merged the comments into an answer. – Bump

Answer 1

That comment is produced by the go/printer code based on the AST passed to it. Some of the AST nodes have a field that flags them as incomplete and this field is used by the printer to decide whether or not to print that comment. However the printer has no way of knowing the rules and reasons for why that field was set to true or false and so by convention it is assumend it was done by a filter, the most common one being exportFilter, hence the language.

The Incomplete field is exported and can be set to true/false by anything that has access to the AST. You could walk the AST yourself setting each Incomplete field to true while leaving the nodes intact and then passing the AST to the printer which would then produce structs with all their fields, exported and unexported, and also that comment.

Godoc filters the AST with ast.FileExports which by default removes only unexported nodes, and then passes the AST to the printer. So in the case of Godoc the "filtered" in that comment is synonymous with "unexported".

---

Playground link to illustrate the printer's behavior.

Bump