Improve embedded package documentation

[egplat]

We should update code comments. See #2326 (comment).

---

Versions

0.9.3

What did you do?

f, err := ferretdb.New(&ferretdb.Config{
		Listener: ferretdb.ListenerConfig{
			TCP: "127.0.0.1:17027",
		},
		Handler:       "pg",
		PostgreSQLURL: "postgres://127.0.0.1:5432/ferretdb", // ferretdb 对齐PostgreSQL的数据库
	})
	if err != nil {
		log.Fatal(err)
	}

ctx, cancel := context.WithCancel(context.Background())
uri := f.MongoDBURI()
fmt.Println(uri)

I created an instance of FerretDB using the code above, but did not run FerretDB.Run(). Then I tried to get the MongoDB uri, which caused the program to block at <-l.tcpListenerReady and ultimately resulted in a deadlock.

What did you expect to see?

Not running FerretDB.Run() and then obtaining the MongoDB uri will not lead to a deadlock.

What did you see instead?

fatal error: all goroutines are asleep - deadlock!

goroutine 1 [chan receive]:
https://github.com/FerretDB/FerretDB/internal/clientconn.(*Listener).TCPAddr(...)
/internal/clientconn/listener.go:321
https://github.com/FerretDB/FerretDB/ferretdb.(*FerretDB).MongoDBURI(0x1057920d8?)
/ferretdb/ferretdb.go:186 +0xdc

Environment

- OS:
- Architecture:
- Version:
- Deployment:
- Deployment details:

[AlekSi]

Unfortunately, starting embedded FerretDB with a Run method is required. For example, when the TCP address is 127.0.0.1:0, we should first begin listening on a TCP socket to know the allocated port number. And we don't want to make Run sometimes required and sometimes not.

But I think we could explain it better in code comments / documentation. Could you send a PR?

[egplat]

收到！

[princejha95]

Will pick this up.

[egplat]

收到！

[princejha95]

Unfortunately, starting embedded FerretDB with a Run method is required. For example, when the TCP address is 127.0.0.1:0, we should first begin listening on a TCP socket to know the allocated port number. And we don't want to make Run sometimes required and sometimes not.

But I think we could explain it better in code comments / documentation. Could you send a PR?

On top of what @AlekSi mentioned, mongoDB URI is formed using the listener's address and in order to get that, listener has to be instantiated which is done by FerretDB.Run() method which implies the necessity of running it before running FerretDB.MongoDBURI() method.

Please correct me if my understanding is wrong.

Thanks

[AlekSi]

That's correct