Add some documentation comments

Matthias Simon created 4 years ago

Change summary

bridge/gitlab/event.go      | 36 +++++++++++++++++++-----------------
bridge/gitlab/gitlab_api.go |  5 +++++
2 files changed, 24 insertions(+), 17 deletions(-)

Detailed changes

bridge/gitlab/event.go

@@ -10,6 +10,14 @@ import (
 	"github.com/xanzy/go-gitlab"
 )
 
+// Event represents a unified GitLab event (note, label or state event).
+type Event interface {
+	ID() string
+	UserID() int
+	Kind() EventKind
+	CreatedAt() time.Time
+}
+
 type EventKind int
 
 const (
@@ -34,23 +42,6 @@ const (
 	EventMentionedInMergeRequest
 )
 
-type Event interface {
-	ID() string
-	UserID() int
-	Kind() EventKind
-	CreatedAt() time.Time
-}
-
-type ErrorEvent struct {
-	Err  error
-	Time time.Time
-}
-
-func (e ErrorEvent) ID() string           { return "" }
-func (e ErrorEvent) UserID() int          { return -1 }
-func (e ErrorEvent) CreatedAt() time.Time { return e.Time }
-func (e ErrorEvent) Kind() EventKind      { return EventError }
-
 type NoteEvent struct{ gitlab.Note }
 
 func (n NoteEvent) ID() string           { return fmt.Sprintf("%d", n.Note.ID) }
@@ -149,6 +140,17 @@ func (s StateEvent) Kind() EventKind {
 	}
 }
 
+type ErrorEvent struct {
+	Err  error
+	Time time.Time
+}
+
+func (e ErrorEvent) ID() string           { return "" }
+func (e ErrorEvent) UserID() int          { return -1 }
+func (e ErrorEvent) CreatedAt() time.Time { return e.Time }
+func (e ErrorEvent) Kind() EventKind      { return EventError }
+
+// SortedEvents consumes an Event-channel and returns an event slice, sorted by creation date, using CreatedAt-method.
 func SortedEvents(c <-chan Event) []Event {
 	var events []Event
 	for e := range c {

bridge/gitlab/gitlab_api.go

@@ -9,6 +9,7 @@ import (
 	"github.com/xanzy/go-gitlab"
 )
 
+// Issues returns a channel with gitlab project issues, ascending order.
 func Issues(ctx context.Context, client *gitlab.Client, pid string, since time.Time) <-chan *gitlab.Issue {
 
 	out := make(chan *gitlab.Issue)
@@ -43,6 +44,7 @@ func Issues(ctx context.Context, client *gitlab.Client, pid string, since time.T
 	return out
 }
 
+// Issues returns a channel with merged, but unsorted gitlab note, label and state change events.
 func IssueEvents(ctx context.Context, client *gitlab.Client, issue *gitlab.Issue) <-chan Event {
 	cs := []<-chan Event{
 		Notes(ctx, client, issue),
@@ -73,6 +75,7 @@ func IssueEvents(ctx context.Context, client *gitlab.Client, issue *gitlab.Issue
 	return out
 }
 
+// Notes returns a channel with note events
 func Notes(ctx context.Context, client *gitlab.Client, issue *gitlab.Issue) <-chan Event {
 
 	out := make(chan Event)
@@ -107,6 +110,7 @@ func Notes(ctx context.Context, client *gitlab.Client, issue *gitlab.Issue) <-ch
 	return out
 }
 
+// LabelEvents returns a channel with label events.
 func LabelEvents(ctx context.Context, client *gitlab.Client, issue *gitlab.Issue) <-chan Event {
 
 	out := make(chan Event)
@@ -140,6 +144,7 @@ func LabelEvents(ctx context.Context, client *gitlab.Client, issue *gitlab.Issue
 	return out
 }
 
+// StateEvents returns a channel with state change events.
 func StateEvents(ctx context.Context, client *gitlab.Client, issue *gitlab.Issue) <-chan Event {
 
 	out := make(chan Event)