dev: Add pkg/commands doc comments

pkg/commands/commands.go

@@ -23,8 +23,10 @@ type CobraRun func(cmd *cobra.Command, args []string)
 
 type CobraRunE func(cmd *cobra.Command, args []string) error
 
+// Option allows extending the command when it is instantiated with New.
 type Option func(*cobra.Command)
 
+// New returns a new command.
 func New(opts ...Option) *cobra.Command {
 	cmd := new(cobra.Command)
 	for _, opt := range opts {
@@ -33,62 +35,77 @@ func New(opts ...Option) *cobra.Command {
 	return cmd
 }
 
+// WithUse returns an option that sets the command's Use field.
 func WithUse(s string) Option {
 	return func(c *cobra.Command) { c.Use = s }
 }
 
+// WithShort returns an option that sets the command's Short field.
 func WithShort(s string) Option {
 	return func(c *cobra.Command) { c.Short = s }
 }
 
+// WithAliases returns an option that sets the command's Aliases field.
 func WithAliases(a []string) Option {
 	return func(c *cobra.Command) { c.Aliases = a }
 }
 
+// WithPersistentPreRun returns an option that sets the command's PersistentPreRun field.
 func WithPersistentPreRun(f CobraRun) Option {
 	return func(c *cobra.Command) { c.PersistentPreRun = f }
 }
 
+// WithPersistentPreRunE returns an option that sets the command's PersistentPreRunE field.
 func WithPersistentPreRunE(f CobraRunE) Option {
 	return func(c *cobra.Command) { c.PersistentPreRunE = f }
 }
 
+// WithPreRun returns an option that sets the command's PreRun field.
 func WithPreRun(f CobraRun) Option {
 	return func(c *cobra.Command) { c.PreRun = f }
 }
 
+// WithPreRunE returns an option that sets the command's PreRunE field.
 func WithPreRunE(f CobraRunE) Option {
 	return func(c *cobra.Command) { c.PreRunE = f }
 }
 
+// WithRun returns an option that sets the command's Run field.
 func WithRun(f CobraRun) Option {
 	return func(c *cobra.Command) { c.Run = f }
 }
 
+// WithRunE returns an option that sets the command's RunE field.
 func WithRunE(f CobraRunE) Option {
 	return func(c *cobra.Command) { c.RunE = f }
 }
 
+// WithPostRun returns an option that sets the command's PostRun field.
 func WithPostRun(f CobraRun) Option {
 	return func(c *cobra.Command) { c.PostRun = f }
 }
 
+// WithPostRunE returns an option that sets the command's PostRunE field.
 func WithPostRunE(f CobraRunE) Option {
 	return func(c *cobra.Command) { c.PostRunE = f }
 }
 
+// WithPersistentPostRun returns an option that sets the command's PersistentPostRun field.
 func WithPersistentPostRun(f CobraRun) Option {
 	return func(c *cobra.Command) { c.PersistentPostRun = f }
 }
 
+// WithPersistentPostRunE returns an option that sets the command's PersistentPostRunE field.
 func WithPersistentPostRunE(f CobraRunE) Option {
 	return func(c *cobra.Command) { c.PersistentPostRunE = f }
 }
 
+// WithSubcommands returns an option that adds commands cmd to the command.
 func WithSubcommands(cmd ...*cobra.Command) Option {
 	return func(c *cobra.Command) { c.AddCommand(cmd...) }
 }
 
+// WithFlagSet returns an option that adds a flag set to the command's flags.
 func WithFlagSet(fs *pflag.FlagSet) Option {
 	return func(c *cobra.Command) { c.Flags().AddFlagSet(fs) }
 }

pkg/commands/source.go

@@ -19,6 +19,7 @@ import (
 	"go.thethings.network/lorawan-stack-migrate/pkg/source"
 )
 
+// Source returns a new source command.
 func Source(sourceName, short string, opts ...Option) *cobra.Command {
 	fs, _ := source.FlagSet(sourceName)
 
@@ -41,6 +42,7 @@ func Source(sourceName, short string, opts ...Option) *cobra.Command {
 	return cmd
 }
 
+// Application returns a new application command.
 func Application(opts ...Option) *cobra.Command {
 	defaultOpts := []Option{
 		WithUse("application ..."),
@@ -51,6 +53,7 @@ func Application(opts ...Option) *cobra.Command {
 	return New(append(defaultOpts, opts...)...)
 }
 
+// Devices returns a new devices command.
 func Devices(opts ...Option) *cobra.Command {
 	defaultOpts := []Option{
 		WithUse("device ..."),
@@ -61,7 +64,8 @@ func Devices(opts ...Option) *cobra.Command {
 	return New(append(defaultOpts, opts...)...)
 }
 
-func SourcePersistentPreRunE() func(*cobra.Command, []string) error {
+// SourcePersistentPreRunE returns a new function that sets the active source.
+func SourcePersistentPreRunE() CobraRunE {
 	return func(cmd *cobra.Command, args []string) error {
 		s := cmd.Name()
 		if ok := source.RootConfig.SetSource(s); !ok {
@@ -70,3 +74,37 @@ func SourcePersistentPreRunE() func(*cobra.Command, []string) error {
 		return ExecuteParentPersistentPreRun(cmd, args)
 	}
 }
+
+// ExecuteParentPersistentPreRun executes cmd's parent's PersistentPreRunE or PersistentPreRun.
+func ExecuteParentPersistentPreRun(cmd *cobra.Command, args []string) error {
+	if !cmd.HasParent() {
+		return nil
+	}
+	p := cmd.Parent()
+
+	if f := p.PersistentPreRunE; f != nil {
+		if err := f(p, args); err != nil {
+			return err
+		}
+	} else if f := p.PersistentPreRun; f != nil {
+		f(p, args)
+	}
+	return nil
+}
+
+// ExecuteParentPersistentPostRun executes cmd's parent's PersistentPostRunE or PersistentPostRun.
+func ExecuteParentPersistentPostRun(cmd *cobra.Command, args []string) error {
+	if !cmd.HasParent() {
+		return nil
+	}
+	p := cmd.Parent()
+
+	if f := p.PersistentPostRunE; f != nil {
+		if err := f(p, args); err != nil {
+			return err
+		}
+	} else if f := p.PersistentPostRun; f != nil {
+		f(p, args)
+	}
+	return nil
+}