go - 在 Go 中通过 Godoc 记录私有(private)结构上的公共(public)方法

Question

我有一个私有(private)结构(实际上不止一个，我为这个例子简化了一点)，我有一个公共(public)函数，满足公共(public)接口(interface)。 这个结构是通过工厂方法(NewX 风格)创建的:

package godocprivate

type PublicInterface interface {
    PublicFunction()
}

type privatestruct struct {
}

func NewPublic() *privatestruct {
    ps := &privatestruct{}
    return ps
}

// PublicFunction does something to be documented
func (self *privatestruct) PublicFunction() {
}

我不能让工厂方法返回公共(public)接口(interface)，因为在我的项目中还有其他接口(interface)需要满足返回值。

我确实想通过 godoc 记录 PublicFunction()，但是因为它在一个私有(private)结构上，所以它没有显示:

是否有任何方法、技巧、解决方法等使 privatestruct.PublicFunction() 在 Godoc 中可见？

我的实际用例更为严重:我确实有不止一个私有(private)结构。它们都满足 PublicInterface，但它们各自的 PublicFunction 实现的内部工作方式不同，因此它们的文档也需要不同......

Answer 1

PublicFunction 使用 PublicStruct，其私有(private)字段将与私有(private)文档一起私有(private)。例如，

package godocprivate

type PublicInterface interface {
    PublicFunction()
}

type privatestruct struct {
}

// PublicStruct is something to be documented except for private fields
type PublicStruct struct {
    privatestruct
}

func NewPublic() *PublicStruct {
    ps := &PublicStruct{}
    return ps
}

// PublicFunction does something to be documented
func (p *PublicStruct) PublicFunction() {
}

创建 PublicStruct 时，每个字段的初始值为零。如果这还不够，请引入工厂 bool 值。例如，

package godocprivate

type PublicInterface interface {
    PublicFunction()
}

type privatestruct struct {
}

// PublicStruct is something to be documented except for private fields
type PublicStruct struct {
    factory bool
    privatestruct
}

func NewPublic() *PublicStruct {
    ps := &PublicStruct{factory: true}
    return ps
}

// PublicFunction does something to be documented
func (p *PublicStruct) PublicFunction() {
    if !p.factory {
        panic("Use NewPublic")
    }
}