From ac40d357f01dd795aff345844298a6db9cd5e843 Mon Sep 17 00:00:00 2001
From: Roman Khimov <roman@nspcc.ru>
Date: Thu, 7 May 2020 22:04:10 +0300
Subject: [PATCH] core: improve documentation a little

---
 pkg/core/blockchain.go | 10 +++++++---
 pkg/core/doc.go        |  5 +++++
 2 files changed, 12 insertions(+), 3 deletions(-)
 create mode 100644 pkg/core/doc.go

diff --git a/pkg/core/blockchain.go b/pkg/core/blockchain.go
index 0ef370b8f..f7c93eb9d 100644
--- a/pkg/core/blockchain.go
+++ b/pkg/core/blockchain.go
@@ -64,7 +64,9 @@ var (
 	persistInterval   = 1 * time.Second
 )
 
-// Blockchain represents the blockchain.
+// Blockchain represents the blockchain. It maintans internal state representing
+// the state of the ledger that can be accessed in various ways and changed by
+// adding new blocks or headers.
 type Blockchain struct {
 	config config.ProtocolConfiguration
 
@@ -130,7 +132,8 @@ type Blockchain struct {
 type headersOpFunc func(headerList *HeaderHashList)
 
 // NewBlockchain returns a new blockchain object the will use the
-// given Store as its underlying storage.
+// given Store as its underlying storage. For it to work correctly you need
+// to spawn a goroutine for its Run method after this initialization.
 func NewBlockchain(s storage.Store, cfg config.ProtocolConfiguration, log *zap.Logger) (*Blockchain, error) {
 	if log == nil {
 		return nil, errors.New("empty logger")
@@ -269,7 +272,8 @@ func (bc *Blockchain) init() error {
 	return nil
 }
 
-// Run runs chain loop.
+// Run runs chain loop, it needs to be run as goroutine and executing it is
+// critical for correct Blockchain operation.
 func (bc *Blockchain) Run() {
 	persistTimer := time.NewTimer(persistInterval)
 	defer func() {
diff --git a/pkg/core/doc.go b/pkg/core/doc.go
new file mode 100644
index 000000000..b0364db7f
--- /dev/null
+++ b/pkg/core/doc.go
@@ -0,0 +1,5 @@
+/*
+Package core implements Neo ledger functionality.
+It's built around the Blockchain structure that maintains state of the ledger.
+*/
+package core