From 5c31d4331cb35ce36e298ea272b39897a2e2adb5 Mon Sep 17 00:00:00 2001
From: Ishank Arora <ishank011@gmail.com>
Date: Wed, 24 Feb 2021 19:06:35 +0100
Subject: [PATCH] Add comments to exported functions

---
 pkg/cbox/publicshare/sql/sql.go |  1 +
 pkg/cbox/share/sql/sql.go       |  2 +-
 pkg/cbox/utils/conversions.go   | 14 ++++++++++++++
 3 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/pkg/cbox/publicshare/sql/sql.go b/pkg/cbox/publicshare/sql/sql.go
index ed0115d7c63..dc921853bbd 100644
--- a/pkg/cbox/publicshare/sql/sql.go
+++ b/pkg/cbox/publicshare/sql/sql.go
@@ -103,6 +103,7 @@ func (m *manager) startJanitorRun() {
 	}
 }
 
+// New returns a new public share manager.
 func New(m map[string]interface{}) (publicshare.Manager, error) {
 	c := &config{}
 	if err := mapstructure.Decode(m, c); err != nil {
diff --git a/pkg/cbox/share/sql/sql.go b/pkg/cbox/share/sql/sql.go
index 842871d3692..5dd6fe8105b 100644
--- a/pkg/cbox/share/sql/sql.go
+++ b/pkg/cbox/share/sql/sql.go
@@ -60,7 +60,7 @@ type mgr struct {
 	db *sql.DB
 }
 
-// New returns a new mgr.
+// New returns a new share manager.
 func New(m map[string]interface{}) (share.Manager, error) {
 	c, err := parseConfig(m)
 	if err != nil {
diff --git a/pkg/cbox/utils/conversions.go b/pkg/cbox/utils/conversions.go
index f4efcbd1ac0..a9ea9ac3641 100644
--- a/pkg/cbox/utils/conversions.go
+++ b/pkg/cbox/utils/conversions.go
@@ -31,6 +31,7 @@ import (
 	typespb "github.com/cs3org/go-cs3apis/cs3/types/v1beta1"
 )
 
+// DBShare stores information about user and public shares.
 type DBShare struct {
 	ID           string
 	UIDOwner     string
@@ -48,6 +49,7 @@ type DBShare struct {
 	State        int
 }
 
+// FormatGrantee formats a CS3API grantee to a string
 func FormatGrantee(g *provider.Grantee) (int, string) {
 	var granteeType int
 	var formattedID string
@@ -64,6 +66,7 @@ func FormatGrantee(g *provider.Grantee) (int, string) {
 	return granteeType, formattedID
 }
 
+// ExtractGrantee retrieves the CS3API grantee from a formatted string
 func ExtractGrantee(t int, g string) *provider.Grantee {
 	var grantee *provider.Grantee
 	switch t {
@@ -79,6 +82,7 @@ func ExtractGrantee(t int, g string) *provider.Grantee {
 	return grantee
 }
 
+// ResourceTypeToItem maps a resource type to an integer
 func ResourceTypeToItem(r provider.ResourceType) string {
 	switch r {
 	case provider.ResourceType_RESOURCE_TYPE_FILE:
@@ -94,6 +98,7 @@ func ResourceTypeToItem(r provider.ResourceType) string {
 	}
 }
 
+// SharePermToInt maps read/write permissions to an integer
 func SharePermToInt(p *provider.ResourcePermissions) int {
 	var perm int
 	if p.CreateContainer {
@@ -104,6 +109,7 @@ func SharePermToInt(p *provider.ResourcePermissions) int {
 	return perm
 }
 
+// IntTosharePerm retrieves read/write permissions from an integer
 func IntTosharePerm(p int) *provider.ResourcePermissions {
 	switch p {
 	case 1:
@@ -141,6 +147,7 @@ func IntTosharePerm(p int) *provider.ResourcePermissions {
 	}
 }
 
+// IntToShareState retrieves the received share state from an integer
 func IntToShareState(g int) collaboration.ShareState {
 	switch g {
 	case 0:
@@ -152,6 +159,7 @@ func IntToShareState(g int) collaboration.ShareState {
 	}
 }
 
+// FormatUserID formats a CS3API user ID to a string
 func FormatUserID(u *userpb.UserId) string {
 	if u.Idp != "" {
 		return fmt.Sprintf("%s:%s", u.OpaqueId, u.Idp)
@@ -159,6 +167,7 @@ func FormatUserID(u *userpb.UserId) string {
 	return u.OpaqueId
 }
 
+// ExtractUserID retrieves a CS3API user ID from a string
 func ExtractUserID(u string) *userpb.UserId {
 	parts := strings.Split(u, ":")
 	if len(parts) > 1 {
@@ -167,6 +176,7 @@ func ExtractUserID(u string) *userpb.UserId {
 	return &userpb.UserId{OpaqueId: parts[0]}
 }
 
+// FormatGroupID formats a CS3API group ID to a string
 func FormatGroupID(u *grouppb.GroupId) string {
 	if u.Idp != "" {
 		return fmt.Sprintf("%s:%s", u.OpaqueId, u.Idp)
@@ -174,6 +184,7 @@ func FormatGroupID(u *grouppb.GroupId) string {
 	return u.OpaqueId
 }
 
+// ExtractGroupID retrieves a CS3API group ID from a string
 func ExtractGroupID(u string) *grouppb.GroupId {
 	parts := strings.Split(u, ":")
 	if len(parts) > 1 {
@@ -182,6 +193,7 @@ func ExtractGroupID(u string) *grouppb.GroupId {
 	return &grouppb.GroupId{OpaqueId: parts[0]}
 }
 
+// ConvertToCS3Share converts a DBShare to a CS3API collaboration share
 func ConvertToCS3Share(s DBShare) *collaboration.Share {
 	ts := &typespb.Timestamp{
 		Seconds: uint64(s.STime),
@@ -200,6 +212,7 @@ func ConvertToCS3Share(s DBShare) *collaboration.Share {
 	}
 }
 
+// ConvertToCS3ReceivedShare converts a DBShare to a CS3API collaboration received share
 func ConvertToCS3ReceivedShare(s DBShare) *collaboration.ReceivedShare {
 	share := ConvertToCS3Share(s)
 	return &collaboration.ReceivedShare{
@@ -208,6 +221,7 @@ func ConvertToCS3ReceivedShare(s DBShare) *collaboration.ReceivedShare {
 	}
 }
 
+// ConvertToCS3PublicShare converts a DBShare to a CS3API public share
 func ConvertToCS3PublicShare(s DBShare) *link.PublicShare {
 	ts := &typespb.Timestamp{
 		Seconds: uint64(s.STime),