英文:
Documenting public methods on private structs via Godoc in Go
问题
我有一个私有结构体（实际上不止一个，我为了这个例子简化了一下），我在上面有一个满足公共接口的公共函数。
这个结构体是通过一个工厂方法（NewX-style）创建的：
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() {
}
我不能让工厂方法返回公共接口，因为在我的项目中还有其他需要返回值满足的接口。
我确实希望通过godoc来记录PublicFunction()，但是因为它在一个私有结构体上，所以它不会显示出来。
有没有办法、技巧、变通方法等等，让privatestruct.PublicFunction()在Godoc中可见？
我的实际用例甚至更严重：我有不止一个私有结构体。它们都满足PublicInterface，但是它们各自的PublicFunction实现的内部工作不同，因此它们的文档也可能需要不同...
英文:
I have a private struct (actually more than one, I simplified a bit for this example) which I have a public function on, that satisfies a public interface.
This struct is created via a factory method (NewX-style):
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() {
}
I cannot make the factory method return the public interface, because there are other interfaces to be satisfied by the returned value, in my project.
I do want to document PublicFunction() via godoc, but because it is on a private struct, it does not show up:
Is there any way, trick, workaround, etc. to make privatestruct.PublicFunction() visible in Godoc?
My actual use case is even more severe: I do have more than one private struct. All of them satisfy PublicInterface, but the inner workings of their respective PublicFunction-implementations differ, hence could their documentations need to be different, too...
答案1
得分: 1
PublicFunction使用PublicStruct，其中私有字段将具有私有文档。例如，
package godocprivate
type PublicInterface interface {
PublicFunction()
}
type privatestruct struct {
}
// PublicStruct是要记录的内容，除了私有字段
type PublicStruct struct {
privatestruct
}
func NewPublic() *PublicStruct {
ps := &PublicStruct{}
return ps
}
// PublicFunction执行一些要记录的操作
func (p *PublicStruct) PublicFunction() {
}
当创建PublicStruct时，每个字段最初都具有零值。如果这不够，可以引入一个工厂布尔值。例如，
package godocprivate
type PublicInterface interface {
PublicFunction()
}
type privatestruct struct {
}
// PublicStruct是要记录的内容，除了私有字段
type PublicStruct struct {
factory bool
privatestruct
}
func NewPublic() *PublicStruct {
ps := &PublicStruct{factory: true}
return ps
}
// PublicFunction执行一些要记录的操作
func (p *PublicStruct) PublicFunction() {
if !p.factory {
panic("使用NewPublic")
}
}
英文:
PublicFunction uses PublicStruct whose private fields will be private with private documentation. For example,
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() {
}
When PublicStruct is created it initially has zero values for each field. If that's not enough, introduce a factory boolean. For example,
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")
}
}
通过集体智慧和协作来改善编程学习和解决问题的方式。致力于成为全球开发者共同参与的知识库，让每个人都能够通过互相帮助和分享经验来进步。
评论