add documentation

Michael Muré created 7 years ago

Change summary

bridge/bridges.go       |  9 +++++++++
bridge/core/bridge.go   | 10 ++++++++++
bridge/github/github.go |  1 +
bug/timeline.go         |  4 ++++
cache/repo_cache.go     |  3 +++
5 files changed, 27 insertions(+)

Detailed changes

bridge/bridges.go

@@ -1,3 +1,4 @@
+// Package bridge contains the high-level public functions to use and manage bridges
 package bridge
 
 import (
@@ -12,22 +13,30 @@ func Targets() []string {
 	return core.Targets()
 }
 
+// Instantiate a new Bridge for a repo, from the given target and name
 func NewBridge(repo *cache.RepoCache, target string, name string) (*core.Bridge, error) {
 	return core.NewBridge(repo, target, name)
 }
 
+// Instantiate a new bridge for a repo, from the combined target and name contained
+// in the full name
 func NewBridgeFullName(repo *cache.RepoCache, fullName string) (*core.Bridge, error) {
 	return core.NewBridgeFullName(repo, fullName)
 }
 
+// Attempt to retrieve a default bridge for the given repo. If zero or multiple
+// bridge exist, it fails.
 func DefaultBridge(repo *cache.RepoCache) (*core.Bridge, error) {
 	return core.DefaultBridge(repo)
 }
 
+// ConfiguredBridges return the list of bridge that are configured for the given
+// repo
 func ConfiguredBridges(repo repository.RepoCommon) ([]string, error) {
 	return core.ConfiguredBridges(repo)
 }
 
+// Remove a configured bridge
 func RemoveBridges(repo repository.RepoCommon, fullName string) error {
 	return core.RemoveBridge(repo, fullName)
 }

bridge/core/bridge.go

@@ -1,3 +1,4 @@
+// Package core contains the target-agnostic code to define and run a bridge
 package core
 
 import (
@@ -44,6 +45,7 @@ func Targets() []string {
 	return result
 }
 
+// Instantiate a new Bridge for a repo, from the given target and name
 func NewBridge(repo *cache.RepoCache, target string, name string) (*Bridge, error) {
 	implType, ok := bridgeImpl[target]
 	if !ok {
@@ -61,6 +63,8 @@ func NewBridge(repo *cache.RepoCache, target string, name string) (*Bridge, erro
 	return bridge, nil
 }
 
+// Instantiate a new bridge for a repo, from the combined target and name contained
+// in the full name
 func NewBridgeFullName(repo *cache.RepoCache, fullName string) (*Bridge, error) {
 	target, name, err := splitFullName(fullName)
 	if err != nil {
@@ -70,6 +74,8 @@ func NewBridgeFullName(repo *cache.RepoCache, fullName string) (*Bridge, error)
 	return NewBridge(repo, target, name)
 }
 
+// Attempt to retrieve a default bridge for the given repo. If zero or multiple
+// bridge exist, it fails.
 func DefaultBridge(repo *cache.RepoCache) (*Bridge, error) {
 	bridges, err := ConfiguredBridges(repo)
 	if err != nil {
@@ -102,6 +108,8 @@ func splitFullName(fullName string) (string, string, error) {
 	return split[0], split[1], nil
 }
 
+// ConfiguredBridges return the list of bridge that are configured for the given
+// repo
 func ConfiguredBridges(repo repository.RepoCommon) ([]string, error) {
 	configs, err := repo.ReadConfigs("git-bug.bridge.")
 	if err != nil {
@@ -136,6 +144,7 @@ func ConfiguredBridges(repo repository.RepoCommon) ([]string, error) {
 	return result, nil
 }
 
+// Remove a configured bridge
 func RemoveBridge(repo repository.RepoCommon, fullName string) error {
 	re, err := regexp.Compile(`^[^\.]+\.[^\.]+$`)
 	if err != nil {
@@ -150,6 +159,7 @@ func RemoveBridge(repo repository.RepoCommon, fullName string) error {
 	return repo.RmConfigs(keyPrefix)
 }
 
+// Configure run the target specific configuration process
 func (b *Bridge) Configure() error {
 	conf, err := b.impl.Configure(b.repo)
 	if err != nil {

bridge/github/github.go

@@ -1,3 +1,4 @@
+// Package github contains the Github bridge implementation
 package github
 
 import (

bug/timeline.go

@@ -10,6 +10,10 @@ type TimelineItem interface {
 }
 
 type CommentHistoryStep struct {
+	// The author of the edition, not necessarily the same as the author of the
+	// original comment
+	Author Person
+	// The new message
 	Message  string
 	UnixTime Timestamp
 }

cache/repo_cache.go

@@ -213,6 +213,7 @@ func (c *RepoCache) buildCache() error {
 	return nil
 }
 
+// ResolveBug retrieve a bug matching the exact given id
 func (c *RepoCache) ResolveBug(id string) (*BugCache, error) {
 	cached, ok := c.bugs[id]
 	if ok {
@@ -230,6 +231,8 @@ func (c *RepoCache) ResolveBug(id string) (*BugCache, error) {
 	return cached, nil
 }
 
+// ResolveBugPrefix retrieve a bug matching an id prefix. It fails if multiple
+// bugs match.
 func (c *RepoCache) ResolveBugPrefix(prefix string) (*BugCache, error) {
 	// preallocate but empty
 	matching := make([]string, 0, 5)