Add Godoc comments

[philippgille]

First of all: Amazing effort to write an independent Bitcoin implementation as an (as it seems) single contributor.

I stumbled upon this thanks to this Tweet, which points to the same author's blog article comparing different Bitcoin node implementations' performance.

I wanted to take a dive into the code, but realized that in many/most packages, for example github.com/piotrnar/gocoin/lib/btc, most exported types and functions don't have any Godoc comment. Some types/functions have comments, but don't adhere to the Godoc format (like beginning with the name of the type/function, as mentioned in this Go Blog article).

See the Godoc of that package here: https://godoc.org/github.com/piotrnar/gocoin/lib/btc

Examples of well documented packages:

• https://godoc.org/github.com/gorilla/websocket
• https://godoc.org/go.uber.org/zap

Proper Godoc comments might be helpful for

1. potential contributors who want to dive into and understand the code and
2. package users who want to use your exported packages as a library for their own applications.

To not export some packages at all you could use an internal directory, as explained in the Go 1.4 release notes.

As a side note, the recently announced official https://go.dev website, which offers an updated / extended version of Godoc, for example to support versioned Go modules, seems to not be able to understand your LICENSE and thus thinks it's not allowed to show your Godoc at all. See https://pkg.go.dev/github.com/piotrnar/gocoin/lib/btc?tab=doc.

“Doc” hidden due to license restrictions.

[piotrnar]

Thank you for your useful input.

That's certainly a valid issue and I hope to start working towards addressing all the things you mentioned. :)

[piotrnar]

To make a proper documentation one needs to understand what kind of audience it is supposed to address.

I am always happy to provide support to anyone who is trying to understand how all this code works inside, assuming he has some basic knowledge about bitcoin in general and just tries to understand this specific implementation.

I believe at the current stage of matter, it is just more efficient for me to answer specific questions, rather then write a technical documentation that will try to address everything.

When I get enough of certain type of questions, then I will know which parts of the code/solution are worth documenting.
The last thing I want to do is spending my time on creating documentation which nobody is really going to use.

So please forgive me a lack of the documentation at this stage of the project, but also know that a legit questions about how to use this code are always welcome and they are actually useful for me, as they give me an indication of what is worth documenting.

Just send any questions you have to [email protected] or to my Telegram messenger @piotrn