Add package-level descriptions in Go docs (plus general approach to auto-generated docs)

[Mr0grog]

Some of the Go packages we generate documentation for don’t have comments describing the package as a whole. Others have them, but they’re extremely minimal. We should have good, rich descriptions with examples for all of them.

Each should contain a clear description of the package, information about how it relates to other packages, any notes about stability (how experimental/subject to change is it?), and at least one small example of basic usage (options might be an exception because it’s just defining types…?).

Relevant packages:

• core/coreapi (no overview) Add package overview comments to coreapi ipfs/kubo#5108
• core/coreapi/interface (one sentence)
• core/coreapi/interface/options (no overview)
• go-ipfs-api (one sentence)

See also this comment on #68.

[jessicaschilling]

Auto-generated Go docs are being generated somewhat differently now -- but we still need to address best approach to this as part of the new docs beta.

[Mr0grog]

Just making sure everyone’s reading this issue the same way…

Auto-generated Go docs are being generated somewhat differently now

I might be misunderstanding, but is this just the fact that “Go Core API” and others in the sidebar now point directly to godoc.org instead of a copy of the docs we’ve generate inside the docs site? If so, that’s more-or-less unrelated to what this issue was inteded to address: making sure the docs that are in the Go source code are correct and get good results when run though godoc.

[jessicaschilling]

@Mr0grog Transitioning to the use of godoc over godoc2md was to address a breaking change in #276 ... you're correct that this doesn't solve the larger issue, which involves thinking through our approach to docs in the Go source code and how we present them better. Thanks for leaning on this one; we're queuing work on those up as part of the docs platform rework, but I haven't been able to capture them in individual issues yet.

[Mr0grog]

👍 Great, just wasn’t sure from the wording and wanted to make sure this wasn’t getting mistaken for something in the docs site source rather than the actual go packages’ source. :)

[jessicaschilling]

Closing this issue, since our overall approach to API/CLI docs is being worked in #393 in Q1 2020. We're also working on migrating go-ipfs docs as a whole over to the new docs beta under #348.