Sample doc format update

[piotrpio]

trafficstars

This is a first attempt to establish a cleaner and more verbose documentation.

These are not full changes! If this approach will be deemed appropriate, I will continue with improving documentation across the whole repository.

Some rules I am trying to follow:

1. Each exported function, method and type has to be documented.
2. Constants and variables should be divided into logical blocks, that way it is displayed nicely in godoc, e.g.:

// Client version and language name.
// Used by nats-server to help identify a client connection.
const (
	Version    = "1.20.0"
	LangString = "go"
)

// Default values used by [Connect] and [GetDefaultOptions].
const (
	DefaultURL                = "nats://127.0.0.1:4222"
	DefaultPort               = 4222
	DefaultMaxReconnect       = 60
	DefaultReconnectWait      = 2 * time.Second
	DefaultReconnectJitter    = 100 * time.Millisecond
	DefaultReconnectJitterTLS = time.Second
	DefaultTimeout            = 2 * time.Second
	DefaultPingInterval       = 2 * time.Minute
	DefaultMaxPingOut         = 2
	DefaultMaxChanLen         = 64 * 1024       // 64k
	DefaultReconnectBufSize   = 8 * 1024 * 1024 // 8MB
	RequestChanLen            = 8
	DefaultDrainTimeout       = 30 * time.Second
)

is formatted to:

3. Each error variable is documented separately.
4. Each function and method should have at least one example in example_test.go.
5. Comments should use links to internal and external documentation whenever it's necessary. (e.g. [*net.Dialer] instead of *net.Dialer or [GetDefaultOptions] instead of GetDefaultOptions().
6. In general, comments in code should not need long blocks of code - examples can be used for that (of course code blocks are still useful at times).
7. Headings can be used whenever we feel like a part of documentation is necessary and can potentially be linked to. Errors block is a good example of that:

[piotrpio]

@mprimi FYI, I can't add you as a reviewer.

[coveralls]

Coverage decreased (-0.04%) to 85.806% when pulling ac9cf54ef7106c6ff21565c22870b5d19b2352e6 on docs-update into 398a1ecb71df5de5d2c8675c9d4615f0aa4574ef on main.

[derekcollison]

Added in @bruth and @gcolliso to take a peek as well.

[Jarema]

That looks nice, but for default format example, I would also use something with a method/function call with an example, as that's the majority of docs.

[Jarema]

The connect example looks ok. One thing that worries me is lack of error handling.

in Rust NATS crate now every single example has proper error handling, as we know (and see on slack) that people copy-paste those examples into their codebases. Problem is - examples would grow a lot in size because of error handling verbosity in Go. Neither seems ok :)

[piotrpio]

@Jarema TBH, I would prefer shorter, more straightforward examples over proper error handling. Go programmers know well enough that every error should be checked and handled, and that's mostly our audience in go client I think.

[bruth]

@piotrpio I think this is great and will have good long-term impact. Of course each language/client has their own method for in-code documentation, but we could establish and promote expectations so any generated docs has the same quality of content.

I also agree with the "Go programmers are are aware and expected to handle errors" argument. The NATS by Example Go examples also omit error handling for brevity.

As an aside, I have been thinking about client/language API docs. As far as I know, all of the languages we officially support have some kind of standard for writing and generating docs. Maybe the exception is the C client :man_shrugging:. For the new docs site, other than hand-written examples, we definitely need code-derived API docs.