通过Godoc在Go中记录私有结构体的公共方法

huangapple go评论114阅读模式
英文:

Documenting public methods on private structs via Godoc in Go

问题

我有一个私有结构体(实际上不止一个,我为了这个例子简化了一下),我在上面有一个满足公共接口的公共函数。

这个结构体是通过一个工厂方法(NewX-style)创建的:

  1. package godocprivate
  2. type PublicInterface interface {
  3. PublicFunction()
  4. }
  5. type privatestruct struct {
  6. }
  7. func NewPublic() *privatestruct {
  8. ps := &privatestruct{}
  9. return ps
  10. }
  11. // PublicFunction does something to be documented
  12. func (self *privatestruct) PublicFunction() {
  13. }

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

我确实希望通过godoc来记录PublicFunction(),但是因为它在一个私有结构体上,所以它不会显示出来。

通过Godoc在Go中记录私有结构体的公共方法

有没有办法、技巧、变通方法等等,让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):

  1. package godocprivate
  2. type PublicInterface interface {
  3. PublicFunction()
  4. }
  5. type privatestruct struct {
  6. }
  7. func NewPublic() *privatestruct {
  8. ps := &privatestruct{}
  9. return ps
  10. }
  11. // PublicFunction does something to be documented
  12. func (self *privatestruct) PublicFunction() {
  13. }

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:

通过Godoc在Go中记录私有结构体的公共方法

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,其中私有字段将具有私有文档。例如,

  1. package godocprivate
  2. type PublicInterface interface {
  3. PublicFunction()
  4. }
  5. type privatestruct struct {
  6. }
  7. // PublicStruct是要记录的内容,除了私有字段
  8. type PublicStruct struct {
  9. privatestruct
  10. }
  11. func NewPublic() *PublicStruct {
  12. ps := &PublicStruct{}
  13. return ps
  14. }
  15. // PublicFunction执行一些要记录的操作
  16. func (p *PublicStruct) PublicFunction() {
  17. }

当创建PublicStruct时,每个字段最初都具有零值。如果这不够,可以引入一个工厂布尔值。例如,

  1. package godocprivate
  2. type PublicInterface interface {
  3. PublicFunction()
  4. }
  5. type privatestruct struct {
  6. }
  7. // PublicStruct是要记录的内容,除了私有字段
  8. type PublicStruct struct {
  9. factory bool
  10. privatestruct
  11. }
  12. func NewPublic() *PublicStruct {
  13. ps := &PublicStruct{factory: true}
  14. return ps
  15. }
  16. // PublicFunction执行一些要记录的操作
  17. func (p *PublicStruct) PublicFunction() {
  18. if !p.factory {
  19. panic("使用NewPublic")
  20. }
  21. }
英文:

PublicFunction uses PublicStruct whose private fields will be private with private documentation. For example,

  1. package godocprivate
  2. type PublicInterface interface {
  3. PublicFunction()
  4. }
  5. type privatestruct struct {
  6. }
  7. // PublicStruct is something to be documented except for private fields
  8. type PublicStruct struct {
  9. privatestruct
  10. }
  11. func NewPublic() *PublicStruct {
  12. ps := &PublicStruct{}
  13. return ps
  14. }
  15. // PublicFunction does something to be documented
  16. func (p *PublicStruct) PublicFunction() {
  17. }

When PublicStruct is created it initially has zero values for each field. If that's not enough, introduce a factory boolean. For example,

  1. package godocprivate
  2. type PublicInterface interface {
  3. PublicFunction()
  4. }
  5. type privatestruct struct {
  6. }
  7. // PublicStruct is something to be documented except for private fields
  8. type PublicStruct struct {
  9. factory bool
  10. privatestruct
  11. }
  12. func NewPublic() *PublicStruct {
  13. ps := &PublicStruct{factory: true}
  14. return ps
  15. }
  16. // PublicFunction does something to be documented
  17. func (p *PublicStruct) PublicFunction() {
  18. if !p.factory {
  19. panic("Use NewPublic")
  20. }
  21. }

huangapple
  • 本文由 发表于 2015年5月8日 03:08:10
  • 转载请务必保留本文链接:https://go.coder-hub.com/30109674.html
匿名

发表评论

匿名网友

:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen:

确定