From a23b56fff90ba4cd4a9737ff71834cdd07e1a14a Mon Sep 17 00:00:00 2001
From: Alex Vanin <alexey@nspcc.ru>
Date: Tue, 13 Jul 2021 20:55:32 +0300
Subject: [PATCH] [#105] reputation: Add docs

Signed-off-by: Alex Vanin <alexey@nspcc.ru>
---
 reputation/doc.go                 | 17 ++++++++++++++++-
 reputation/reputation_contract.go | 15 ++++++++++++++-
 2 files changed, 30 insertions(+), 2 deletions(-)

diff --git a/reputation/doc.go b/reputation/doc.go
index a8668d8..f1d6979 100644
--- a/reputation/doc.go
+++ b/reputation/doc.go
@@ -1,2 +1,17 @@
-// Reputaiton contract description.
+/*
+Reputation contract is a contract deployed in NeoFS side chain.
+
+Inner Ring nodes produce data audit for each container in each epoch. In the end
+nodes produce DataAuditResult structure that contains information about audit
+progress. Reputation contract provides storage for such structures and simple
+interface to iterate over available DataAuditResults on specified epoch.
+
+During settlement process, Alphabet nodes fetch all DataAuditResult structures
+from the epoch and execute balance transfers from data owners to Storage and
+Inner Ring nodes, if data audit succeed.
+
+Contract notifications
+
+Reputation contract does not produce notifications to process.
+*/
 package reputation
diff --git a/reputation/reputation_contract.go b/reputation/reputation_contract.go
index cffd5d3..7debcda 100644
--- a/reputation/reputation_contract.go
+++ b/reputation/reputation_contract.go
@@ -44,6 +44,8 @@ func _deploy(data interface{}, isUpdate bool) {
 	runtime.Log("reputation contract initialized")
 }
 
+// Migrate method updates contract source code and manifest. Can be invoked
+// only by contract owner.
 func Migrate(script []byte, manifest []byte, data interface{}) bool {
 	ctx := storage.GetReadOnlyContext()
 
@@ -58,6 +60,12 @@ func Migrate(script []byte, manifest []byte, data interface{}) bool {
 	return true
 }
 
+// Put method saves DataAuditResult in contract storage. Can be invoked only by
+// Inner Ring nodes. Does not require multi signature invocations.
+//
+// Epoch is an epoch number when DataAuditResult structure was generated.
+// PeerID contains public keys of Inner Ring node that produced DataAuditResult.
+// Value contains stable marshaled structure of DataAuditResult.
 func Put(epoch int, peerID []byte, value []byte) {
 	ctx := storage.GetContext()
 	notaryDisabled := storage.Get(ctx, notaryDisabledKey).(bool)
@@ -103,11 +111,15 @@ func Put(epoch int, peerID []byte, value []byte) {
 	storage.Put(ctx, id, rawValues)
 }
 
+// Get method returns list of all stable marshaled DataAuditResult structures
+// produced by specified Inner Ring node in specified epoch.
 func Get(epoch int, peerID []byte) [][]byte {
 	id := storageID(epoch, peerID)
 	return GetByID(id)
 }
 
+// GetByID method returns list of all stable marshaled DataAuditResult with
+// specified id. Use ListByEpoch method to obtain id.
 func GetByID(id []byte) [][]byte {
 	ctx := storage.GetReadOnlyContext()
 
@@ -120,7 +132,7 @@ func GetByID(id []byte) [][]byte {
 }
 
 // ListByEpoch returns list of IDs that may be used to get reputation data
-// via GetByID method.
+// with GetByID method.
 func ListByEpoch(epoch int) [][]byte {
 	ctx := storage.GetReadOnlyContext()
 	var buf interface{} = epoch
@@ -148,6 +160,7 @@ loop:
 	return result
 }
 
+// Version returns version of the contract.
 func Version() int {
 	return version
 }