From b56e028733557bcc05329c974cb741b28a373bf8 Mon Sep 17 00:00:00 2001
From: Roman Khimov <roman@nspcc.ru>
Date: Fri, 19 Mar 2021 12:11:48 +0300
Subject: [PATCH] *: add more package-specific documentation

For the most important packages at least.
---
 pkg/compiler/doc.go                            | 4 ++++
 pkg/config/doc.go                              | 4 ++++
 pkg/config/netmode/doc.go                      | 4 ++++
 pkg/consensus/doc.go                           | 7 +++++++
 pkg/core/block/doc.go                          | 6 ++++++
 pkg/core/interop/doc.go                        | 7 +++++++
 pkg/core/native/doc.go                         | 4 ++++
 pkg/core/transaction/doc.go                    | 6 ++++++
 pkg/crypto/doc.go                              | 6 ++++++
 pkg/crypto/hash/doc.go                         | 6 ++++++
 pkg/crypto/keys/doc.go                         | 4 ++++
 pkg/encoding/address/doc.go                    | 4 ++++
 pkg/encoding/bigint/doc.go                     | 4 ++++
 pkg/encoding/fixedn/doc.go                     | 4 ++++
 pkg/interop/math/math.go                       | 3 +++
 pkg/interop/native/crypto/crypto.go            | 4 ++++
 pkg/interop/native/gas/gas.go                  | 4 ++++
 pkg/interop/native/ledger/ledger.go            | 4 ++++
 pkg/interop/native/management/management.go    | 4 ++++
 pkg/interop/native/nameservice/name_service.go | 4 ++++
 pkg/interop/native/neo/neo.go                  | 6 ++++++
 pkg/interop/native/notary/notary.go            | 5 +++++
 pkg/interop/native/oracle/oracle.go            | 5 +++++
 pkg/interop/native/policy/policy.go            | 4 ++++
 pkg/interop/native/roles/roles.go              | 8 +++++++-
 pkg/interop/native/std/std.go                  | 4 ++++
 pkg/interop/neogointernal/doc.go               | 5 +++++
 27 files changed, 129 insertions(+), 1 deletion(-)
 create mode 100644 pkg/compiler/doc.go
 create mode 100644 pkg/config/doc.go
 create mode 100644 pkg/config/netmode/doc.go
 create mode 100644 pkg/consensus/doc.go
 create mode 100644 pkg/core/block/doc.go
 create mode 100644 pkg/core/interop/doc.go
 create mode 100644 pkg/core/native/doc.go
 create mode 100644 pkg/core/transaction/doc.go
 create mode 100644 pkg/crypto/doc.go
 create mode 100644 pkg/crypto/hash/doc.go
 create mode 100644 pkg/crypto/keys/doc.go
 create mode 100644 pkg/encoding/address/doc.go
 create mode 100644 pkg/encoding/bigint/doc.go
 create mode 100644 pkg/encoding/fixedn/doc.go
 create mode 100644 pkg/interop/neogointernal/doc.go

diff --git a/pkg/compiler/doc.go b/pkg/compiler/doc.go
new file mode 100644
index 000000000..6d5842f04
--- /dev/null
+++ b/pkg/compiler/doc.go
@@ -0,0 +1,4 @@
+/*
+Package compiler implements Go to NEF smart contract compiler.
+*/
+package compiler
diff --git a/pkg/config/doc.go b/pkg/config/doc.go
new file mode 100644
index 000000000..645279cdf
--- /dev/null
+++ b/pkg/config/doc.go
@@ -0,0 +1,4 @@
+/*
+Package config contains NeoGo node configuration definition.
+*/
+package config
diff --git a/pkg/config/netmode/doc.go b/pkg/config/netmode/doc.go
new file mode 100644
index 000000000..54c3d609d
--- /dev/null
+++ b/pkg/config/netmode/doc.go
@@ -0,0 +1,4 @@
+/*
+Package netmode contains well-known network magic numbers.
+*/
+package netmode
diff --git a/pkg/consensus/doc.go b/pkg/consensus/doc.go
new file mode 100644
index 000000000..6eaa2f4f1
--- /dev/null
+++ b/pkg/consensus/doc.go
@@ -0,0 +1,7 @@
+/*
+Package consensus contains Neo consensus node implementation.
+
+It uses external dBFT library for the core algorithm and basically joins this
+library with Neo node internals implemented in NeoGo.
+*/
+package consensus
diff --git a/pkg/core/block/doc.go b/pkg/core/block/doc.go
new file mode 100644
index 000000000..c69918fb5
--- /dev/null
+++ b/pkg/core/block/doc.go
@@ -0,0 +1,6 @@
+/*
+Package block contains Neo block definition.
+
+This is one of the core structures of Neo blockchain.
+*/
+package block
diff --git a/pkg/core/interop/doc.go b/pkg/core/interop/doc.go
new file mode 100644
index 000000000..0d080ddb6
--- /dev/null
+++ b/pkg/core/interop/doc.go
@@ -0,0 +1,7 @@
+/*
+Package interop contains implementations of Neo interop functions.
+
+This is not the package you use from smart contracts, refer to pkg/interop
+for that.
+*/
+package interop
diff --git a/pkg/core/native/doc.go b/pkg/core/native/doc.go
new file mode 100644
index 000000000..72fe6a758
--- /dev/null
+++ b/pkg/core/native/doc.go
@@ -0,0 +1,4 @@
+/*
+Package native contains Neo native contracts.
+*/
+package native
diff --git a/pkg/core/transaction/doc.go b/pkg/core/transaction/doc.go
new file mode 100644
index 000000000..41daa0dd8
--- /dev/null
+++ b/pkg/core/transaction/doc.go
@@ -0,0 +1,6 @@
+/*
+Package transaction contains Neo transaction definition.
+
+This is one of the core structures of Neo blockchain.
+*/
+package transaction
diff --git a/pkg/crypto/doc.go b/pkg/crypto/doc.go
new file mode 100644
index 000000000..ca41a956d
--- /dev/null
+++ b/pkg/crypto/doc.go
@@ -0,0 +1,6 @@
+/*
+Package crypto contains implementation of crypto functions used by Neo.
+
+This package itself just has some useful interfaces.
+*/
+package crypto
diff --git a/pkg/crypto/hash/doc.go b/pkg/crypto/hash/doc.go
new file mode 100644
index 000000000..198b4f523
--- /dev/null
+++ b/pkg/crypto/hash/doc.go
@@ -0,0 +1,6 @@
+/*
+Package hash contains wrappers for Neo hashing algorithms.
+
+It also implements Merkle tree.
+*/
+package hash
diff --git a/pkg/crypto/keys/doc.go b/pkg/crypto/keys/doc.go
new file mode 100644
index 000000000..9239e185b
--- /dev/null
+++ b/pkg/crypto/keys/doc.go
@@ -0,0 +1,4 @@
+/*
+Package keys wraps public/private keys and implements NEP-2 and WIF.
+*/
+package keys
diff --git a/pkg/encoding/address/doc.go b/pkg/encoding/address/doc.go
new file mode 100644
index 000000000..8ce8c7c9a
--- /dev/null
+++ b/pkg/encoding/address/doc.go
@@ -0,0 +1,4 @@
+/*
+Package address implements conversion of script hash to/from Neo address.
+*/
+package address
diff --git a/pkg/encoding/bigint/doc.go b/pkg/encoding/bigint/doc.go
new file mode 100644
index 000000000..3e2c1d4a6
--- /dev/null
+++ b/pkg/encoding/bigint/doc.go
@@ -0,0 +1,4 @@
+/*
+Package bigint implements Neo-specific big.Int (de)serialization to/from []byte.
+*/
+package bigint
diff --git a/pkg/encoding/fixedn/doc.go b/pkg/encoding/fixedn/doc.go
new file mode 100644
index 000000000..dc053fbdd
--- /dev/null
+++ b/pkg/encoding/fixedn/doc.go
@@ -0,0 +1,4 @@
+/*
+Package fixedn implements fixed point integers with arbitrary precision.
+*/
+package fixedn
diff --git a/pkg/interop/math/math.go b/pkg/interop/math/math.go
index 6097bae1c..851e318a4 100644
--- a/pkg/interop/math/math.go
+++ b/pkg/interop/math/math.go
@@ -1,3 +1,6 @@
+/*
+Package math provides access to useful numeric functions available in Neo VM.
+*/
 package math
 
 import "github.com/nspcc-dev/neo-go/pkg/interop/neogointernal"
diff --git a/pkg/interop/native/crypto/crypto.go b/pkg/interop/native/crypto/crypto.go
index 32684d551..1a2c8709f 100644
--- a/pkg/interop/native/crypto/crypto.go
+++ b/pkg/interop/native/crypto/crypto.go
@@ -1,3 +1,7 @@
+/*
+Package crypto provides interface to CryptoLib native contract.
+It implements some cryptographic functions.
+*/
 package crypto
 
 import (
diff --git a/pkg/interop/native/gas/gas.go b/pkg/interop/native/gas/gas.go
index e93941429..1d0cc9329 100644
--- a/pkg/interop/native/gas/gas.go
+++ b/pkg/interop/native/gas/gas.go
@@ -1,3 +1,7 @@
+/*
+Package gas provides interface to GasToken native contract.
+It implements regular NEP-17 functions for GAS token.
+*/
 package gas
 
 import (
diff --git a/pkg/interop/native/ledger/ledger.go b/pkg/interop/native/ledger/ledger.go
index 1f3a124ba..028eb6e59 100644
--- a/pkg/interop/native/ledger/ledger.go
+++ b/pkg/interop/native/ledger/ledger.go
@@ -1,3 +1,7 @@
+/*
+Package ledger provides interface to LedgerContract native contract.
+It allows to access ledger contents like transactions and blocks.
+*/
 package ledger
 
 import (
diff --git a/pkg/interop/native/management/management.go b/pkg/interop/native/management/management.go
index d65e9a1fe..97c109391 100644
--- a/pkg/interop/native/management/management.go
+++ b/pkg/interop/native/management/management.go
@@ -1,3 +1,7 @@
+/*
+Package management provides interface to ContractManagement native contract.
+It allows to get/deploy/update contracts as well as get/set deployment fee.
+*/
 package management
 
 import (
diff --git a/pkg/interop/native/nameservice/name_service.go b/pkg/interop/native/nameservice/name_service.go
index ebb24fd26..065f6d747 100644
--- a/pkg/interop/native/nameservice/name_service.go
+++ b/pkg/interop/native/nameservice/name_service.go
@@ -1,3 +1,7 @@
+/*
+Package nameservice provides interface to NameService native contract.
+It's a NEP-11 contract implementing a domain name service.
+*/
 package nameservice
 
 import (
diff --git a/pkg/interop/native/neo/neo.go b/pkg/interop/native/neo/neo.go
index 8144986f3..b72a16404 100644
--- a/pkg/interop/native/neo/neo.go
+++ b/pkg/interop/native/neo/neo.go
@@ -1,3 +1,9 @@
+/*
+Package neo provides interface to NeoToken native contract.
+NEO token is special, it's not just a regular NEP-17 contract, it also
+provides access to chain-specific settings and implements commmittee
+voting system.
+*/
 package neo
 
 import (
diff --git a/pkg/interop/native/notary/notary.go b/pkg/interop/native/notary/notary.go
index ed83dff4d..67c2861d7 100644
--- a/pkg/interop/native/notary/notary.go
+++ b/pkg/interop/native/notary/notary.go
@@ -1,3 +1,8 @@
+/*
+Package notary provides interface to Notary native contract.
+This contract is a NeoGo extension and is not available on regular Neo
+networks. To use it you need to have this extension enabled on the network.
+*/
 package notary
 
 import (
diff --git a/pkg/interop/native/oracle/oracle.go b/pkg/interop/native/oracle/oracle.go
index edb6534de..44329d354 100644
--- a/pkg/interop/native/oracle/oracle.go
+++ b/pkg/interop/native/oracle/oracle.go
@@ -1,3 +1,8 @@
+/*
+Package oracle provides interface to OracleContract native contract.
+Oracles allow you to get external (non-blockchain) data using HTTPS or NeoFS
+protocols.
+*/
 package oracle
 
 import (
diff --git a/pkg/interop/native/policy/policy.go b/pkg/interop/native/policy/policy.go
index 4acfc97ad..37272f81d 100644
--- a/pkg/interop/native/policy/policy.go
+++ b/pkg/interop/native/policy/policy.go
@@ -1,3 +1,7 @@
+/*
+Package policy provides interface to PolicyContract native contract.
+This contract holds various network-wide settings.
+*/
 package policy
 
 import (
diff --git a/pkg/interop/native/roles/roles.go b/pkg/interop/native/roles/roles.go
index b095466fc..6ccdb00a0 100644
--- a/pkg/interop/native/roles/roles.go
+++ b/pkg/interop/native/roles/roles.go
@@ -1,3 +1,8 @@
+/*
+Package roles provides interface to RoleManagement native contract.
+Role management contract is used by committee to designate some nodes as
+providing some service on the network.
+*/
 package roles
 
 import (
@@ -15,7 +20,8 @@ type Role byte
 const (
 	StateValidator Role = 4
 	Oracle         Role = 8
-	P2PNotary      Role = 128
+	// P2PNotary is an extension of Neo protocol available on specifically configured NeoGo networks.
+	P2PNotary Role = 128
 )
 
 // GetDesignatedByRole represents `getDesignatedByRole` method of RoleManagement native contract.
diff --git a/pkg/interop/native/std/std.go b/pkg/interop/native/std/std.go
index 3fcc5332a..fa5f4dadc 100644
--- a/pkg/interop/native/std/std.go
+++ b/pkg/interop/native/std/std.go
@@ -1,3 +1,7 @@
+/*
+Package std provides interface to StdLib native contract.
+It implements various useful conversion functions.
+*/
 package std
 
 import (
diff --git a/pkg/interop/neogointernal/doc.go b/pkg/interop/neogointernal/doc.go
new file mode 100644
index 000000000..11e1b5025
--- /dev/null
+++ b/pkg/interop/neogointernal/doc.go
@@ -0,0 +1,5 @@
+/*
+Package neogointernal contains definitions of compiler intrinsics.
+It's not intended to be used directly by smart contracts.
+*/
+package neogointernal