Provide overview and synopsis for packages

[orpheuslummis]

The comment above the package declaration defines the package's overview. The first line of that overview is the synopsis.

Examples:

• Synopses are the texts on the right of the table of the list of standard library packages https://pkg.go.dev/std.
• The first section of documentation of a package is the overview, such as in https://pkg.go.dev/[email protected].

[jsimnz]

I can't remember, does this apply to any go file within a package, or just the doc.go file?

[orpheuslummis]

I understand doc.go to be a convention and not a special file. All files with suffix .go related to a package are imported when generating documentation with go doc. It seems good practice when using multiple files for a package to have for it a doc.go with the overview, with the first sentence defining its synopsis. The first comment at the top of file is ignored, making it a good place to include a license.

At least with the godoc tool, when multiple Overview comments are defined for a package they are all appended together under the Overview section of the documentation page.

References:

• Package doc extracts source code documentation from a Go AST. https://pkg.go.dev/go/[email protected]
• Line 179 of go doc code https://go.dev/src/go/doc/doc.go the inclusion of files related to an AST package

[jsimnz]

Alright, thats good to know!

[orpheuslummis]

Request of suggestions of one-sentence summaries (each package's Sypnopsis) for the following packages:

• core
• core/crdt
• store
• merkle/clock
• merkle/crdt
• db/base
• db/container
• db/fetcher
• datastores/iterable
• datastores/badger

[orpheuslummis]

related to #153

[orpheuslummis]

closed by #533