Directives are excluded from extracted docs (#37974). In addition to comments matched by the //[a-z0-9]+:[a-z0-9] pattern, the //line comment is excluded. Maybe the CGO //export comment should be excluded as well.
Comment From: mvdan
I think you meant https://github.com/golang/go/issues/37974?
Comment From: nd
Thanks, fixed
Comment From: ianlancetaylor
@rsc @griesemer Any concerns about handling //export in doc comments as we handle //go: comments? I guess this would be a one-off special case.
Another option would be to migrate toward //go:export comments.
Comment From: ianlancetaylor
Setting Go1.15 milestone since this functionality is new in the 1.15 release. It can be done later, though.
Comment From: griesemer
Wouldn't one want to see //export comments in documentation? How would one be able to tell that the marked Go function can be used from C?
But assuming that excluding these comments in the documentation is ok, moving to //go:export would not require another special case which I think would be preferable. The tools would have to recognize both indefinitely (or at least for a some time), but over time the //export comments would disappear in the documentation as code is adjusted. Does that sound about right?
Comment From: ianlancetaylor
Changing this into a cmd/cgo change to use //go:export.
Comment From: gopherbot
Change https://golang.org/cl/240777 mentions this issue: cmd/cgo: recognize //go:export like //export
Comment From: jimmyfrasche
I filed #68061 as an umbrella proposal which contains this as a special case so I'm closing this issue for now. It may be repopened later if the proposal is rejected.