From a4b218adec59d5c7de564dfeef4729c4615906d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michael=20Mur=C3=A9?= Date: Mon, 1 Oct 2018 21:47:12 +0200 Subject: [PATCH] add documentation --- 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(+) diff --git a/bridge/bridges.go b/bridge/bridges.go index bfd851aaffd406f3a7ea5941bcad853d722493fa..1ffa74b68b4d71ff724726d5cac0813076543ba4 100644 --- a/bridge/bridges.go +++ b/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) } diff --git a/bridge/core/bridge.go b/bridge/core/bridge.go index dd1f13372c464d09af8e11b67da7ce2227153b0a..69e9e52250877d7948678858610685d5d0592ff3 100644 --- a/bridge/core/bridge.go +++ b/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 { diff --git a/bridge/github/github.go b/bridge/github/github.go index a8371637187fc52f1d722cec367d59381ac7d5c7..b70a89db4d6bef29720fc9df4ec1a51ee2dd0096 100644 --- a/bridge/github/github.go +++ b/bridge/github/github.go @@ -1,3 +1,4 @@ +// Package github contains the Github bridge implementation package github import ( diff --git a/bug/timeline.go b/bug/timeline.go index f2feafbae82f3fa3f0727d7bf853c15827bde298..b5aa22a93739e4b741e871109190b754b012ea6d 100644 --- a/bug/timeline.go +++ b/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 } diff --git a/cache/repo_cache.go b/cache/repo_cache.go index 0de5bf07a7e6eeae580af719d35d6b9bfc541f1f..ecfb7131a22a834f150986c1b6bb78889a65ac5c 100644 --- a/cache/repo_cache.go +++ b/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)