From 6c0553da474fbb6bf70cb917187cbcfb0e2e548c Mon Sep 17 00:00:00 2001
From: Roman Khimov <roman@nspcc.ru>
Date: Mon, 18 May 2020 14:23:55 +0300
Subject: [PATCH] interop/header: update documentation

---
 pkg/interop/header/header.go | 38 ++++++++++++++++++++++++------------
 1 file changed, 26 insertions(+), 12 deletions(-)

diff --git a/pkg/interop/header/header.go b/pkg/interop/header/header.go
index 44fc2d9e6..37abe9676 100644
--- a/pkg/interop/header/header.go
+++ b/pkg/interop/header/header.go
@@ -1,47 +1,61 @@
+/*
+Package header contains functions working with block headers.
+*/
 package header
 
-// Package header provides function signatures that can be used inside
-// smart contracts that are written in the neo-go framework.
-
-// Header stubs a NEO block header type.
+// Header represents Neo block header type, it's an opaque data structure that
+// can be used by functions from this package. You can create it with
+// blockchain.GetHeader. In its function it's similar to the Header class
+// of the Neo .net framework.
 type Header struct{}
 
-// GetIndex returns the index of the given header.
+// GetIndex returns the index (height) of the given header. It uses
+// `Neo.Header.GetIndex` syscall.
 func GetIndex(h Header) int {
 	return 0
 }
 
-// GetHash returns the hash of the given header.
+// GetHash returns the hash (256-bit BE value packed into 32 byte slice) of the
+// given header (which also is a hash of the block). It uses `Neo.Header.GetHash`
+// syscall.
 func GetHash(h Header) []byte {
 	return nil
 }
 
-// GetPrevHash returns the previous hash of the given header.
+// GetPrevHash returns the hash (256-bit BE value packed into 32 byte slice) of
+// the previous block stored in the given header. It uses `Neo.Header.GetPrevHash`
+// syscall.
 func GetPrevHash(h Header) []byte {
 	return nil
 }
 
-// GetTimestamp returns the timestamp of the given header.
+// GetTimestamp returns the timestamp of the given header. It uses
+// `Neo.Header.GetTimestamp` syscall.
 func GetTimestamp(h Header) int {
 	return 0
 }
 
-// GetVersion returns the version of the given header.
+// GetVersion returns the version of the given header. It uses
+// `Neo.Header.GetVersion` syscall.
 func GetVersion(h Header) int {
 	return 0
 }
 
-// GetMerkleRoot returns the merkle root of the given header.
+// GetMerkleRoot returns the Merkle root (256-bit BE value packed into 32 byte
+// slice) of the given header. It uses `Neo.Header.GetMerkleRoot` syscall.
 func GetMerkleRoot(h Header) []byte {
 	return nil
 }
 
-// GetConsensusData returns the consensus data of the given header.
+// GetConsensusData returns the consensus data (nonce) of the given header.
+// It uses `Neo.Header.GetConsensusData` syscall.
 func GetConsensusData(h Header) int {
 	return 0
 }
 
-// GetNextConsensus returns the next consensus of the given header.
+// GetNextConsensus returns the next consensus field (verification script hash,
+// 160-bit BE value packed into 20 byte slice) of the given header. It uses
+// `Neo.Header.GetNextConsensus` syscall.
 func GetNextConsensus(h Header) []byte {
 	return nil
 }