[cli] add comments (hasura#4)

shahidhk · web-flow · commit 6d0d75fbe3ca · 2018-06-28T14:06:25.000+05:30
Especially for godoc
diff --git a/cli/commands/console.go b/cli/commands/console.go
@@ -40,7 +40,7 @@ func NewConsoleCmd(ec *cli.ExecutionContext) *cobra.Command {
 			return ec.Validate()
 		},
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return opts.Run()
+			return opts.run()
 		},
 	}
 	f := consoleCmd.Flags()
@@ -71,7 +71,7 @@ type consoleOptions struct {
 	WG *sync.WaitGroup
 }
 
-func (o *consoleOptions) Run() error {
+func (o *consoleOptions) run() error {
 	log := o.EC.Logger
 	// Switch to "release" mode in production.
 	gin.SetMode(gin.ReleaseMode)
diff --git a/cli/commands/init.go b/cli/commands/init.go
@@ -41,7 +41,7 @@ func NewInitCmd(ec *cli.ExecutionContext) *cobra.Command {
 			return ec.Prepare()
 		},
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return opts.Run()
+			return opts.run()
 		},
 	}
 
@@ -60,7 +60,7 @@ type initOptions struct {
 	InitDir   string
 }
 
-func (o *initOptions) Run() error {
+func (o *initOptions) run() error {
 	if o.EC.ExecutionDirectory == "" {
 		o.EC.ExecutionDirectory = o.InitDir
 	}
diff --git a/cli/commands/metadata.go b/cli/commands/metadata.go
@@ -18,9 +18,9 @@ func NewMetadataCmd(ec *cli.ExecutionContext) *cobra.Command {
 		},
 	}
 	metadataCmd.AddCommand(
-		NewMetadataExportCmd(ec),
-		NewMetadataResetCmd(ec),
-		NewMetadataApplyCmd(ec),
+		newMetadataExportCmd(ec),
+		newMetadataResetCmd(ec),
+		newMetadataApplyCmd(ec),
 	)
 	f := metadataCmd.PersistentFlags()
 	f.String("endpoint", "", "http(s) endpoint for Hasura GraphQL Engine")
diff --git a/cli/commands/metadata_apply.go b/cli/commands/metadata_apply.go
@@ -9,7 +9,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
-func NewMetadataApplyCmd(ec *cli.ExecutionContext) *cobra.Command {
+func newMetadataApplyCmd(ec *cli.ExecutionContext) *cobra.Command {
 	opts := &metadataApplyOptions{
 		EC:         ec,
 		actionType: "apply",
@@ -22,7 +22,7 @@ func NewMetadataApplyCmd(ec *cli.ExecutionContext) *cobra.Command {
   hasura metadata apply`,
 		SilenceUsage: true,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return opts.Run()
+			return opts.run()
 		},
 	}
 
@@ -35,7 +35,7 @@ type metadataApplyOptions struct {
 	actionType string
 }
 
-func (o *metadataApplyOptions) Run() error {
+func (o *metadataApplyOptions) run() error {
 	dbURL, err := url.Parse(o.EC.Config.Endpoint)
 	if err != nil {
 		return errors.Wrap(err, "error parsing Endpoint")
diff --git a/cli/commands/metadata_export.go b/cli/commands/metadata_export.go
@@ -9,7 +9,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
-func NewMetadataExportCmd(ec *cli.ExecutionContext) *cobra.Command {
+func newMetadataExportCmd(ec *cli.ExecutionContext) *cobra.Command {
 	opts := &metadataExportOptions{
 		EC:         ec,
 		actionType: "export",
@@ -22,7 +22,7 @@ func NewMetadataExportCmd(ec *cli.ExecutionContext) *cobra.Command {
   hasura metadata export`,
 		SilenceUsage: true,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return opts.Run()
+			return opts.run()
 		},
 	}
 
@@ -35,7 +35,7 @@ type metadataExportOptions struct {
 	actionType string
 }
 
-func (o *metadataExportOptions) Run() error {
+func (o *metadataExportOptions) run() error {
 	dbURL, err := url.Parse(o.EC.Config.Endpoint)
 	if err != nil {
 		return errors.Wrap(err, "error parsing Endpoint")
diff --git a/cli/commands/metadata_reset.go b/cli/commands/metadata_reset.go
@@ -9,7 +9,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
-func NewMetadataResetCmd(ec *cli.ExecutionContext) *cobra.Command {
+func newMetadataResetCmd(ec *cli.ExecutionContext) *cobra.Command {
 	opts := &metadataResetOptions{
 		EC:         ec,
 		actionType: "reset",
@@ -22,7 +22,7 @@ func NewMetadataResetCmd(ec *cli.ExecutionContext) *cobra.Command {
   hasura metadata reset`,
 		SilenceUsage: true,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return opts.Run()
+			return opts.run()
 		},
 	}
 
@@ -35,7 +35,7 @@ type metadataResetOptions struct {
 	actionType string
 }
 
-func (o *metadataResetOptions) Run() error {
+func (o *metadataResetOptions) run() error {
 	dbURL, err := url.Parse(o.EC.Config.Endpoint)
 	if err != nil {
 		return errors.Wrap(err, "error parsing Endpoint")
diff --git a/cli/commands/migrate.go b/cli/commands/migrate.go
@@ -20,9 +20,9 @@ func NewMigrateCmd(ec *cli.ExecutionContext) *cobra.Command {
 		},
 	}
 	migrateCmd.AddCommand(
-		NewMigrateApplyCmd(ec),
-		NewMigrateStatusCmd(ec),
-		NewMigrateCreateCmd(ec),
+		newMigrateApplyCmd(ec),
+		newMigrateStatusCmd(ec),
+		newMigrateCreateCmd(ec),
 	)
 	f := migrateCmd.PersistentFlags()
 	f.String("endpoint", "", "http(s) endpoint for Hasura GraphQL Engine")
diff --git a/cli/commands/migrate_apply.go b/cli/commands/migrate_apply.go
@@ -11,15 +11,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
-var (
-	UP_MIGRATION_HELP      = "apply all or N up migration steps"
-	DOWN_MIGRATION_HELP    = "apply all or N down migration steps"
-	VERSION_MIGRATION_HELP = "migrate the database to a specific version specified by the timestamp"
-)
-
-const FLAG_NOT_SET = ""
-
-func NewMigrateApplyCmd(ec *cli.ExecutionContext) *cobra.Command {
+func newMigrateApplyCmd(ec *cli.ExecutionContext) *cobra.Command {
 	opts := &migrateApplyOptions{
 		EC: ec,
 	}
@@ -28,15 +20,15 @@ func NewMigrateApplyCmd(ec *cli.ExecutionContext) *cobra.Command {
 		Short:        "Apply migrations on the database",
 		SilenceUsage: true,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return opts.Run()
+			return opts.run()
 		},
 	}
 	f := migrateApplyCmd.Flags()
 
-	f.StringVar(&opts.upMigration, "up", FLAG_NOT_SET, UP_MIGRATION_HELP)
-	f.StringVar(&opts.downMigration, "down", FLAG_NOT_SET, DOWN_MIGRATION_HELP)
-	f.StringVar(&opts.versionMigration, "version", FLAG_NOT_SET, VERSION_MIGRATION_HELP)
-	f.StringVar(&opts.typeMigration, "type", FLAG_NOT_SET, VERSION_MIGRATION_HELP)
+	f.StringVar(&opts.upMigration, "up", "", "apply all or N up migration steps")
+	f.StringVar(&opts.downMigration, "down", "", "apply all or N down migration steps")
+	f.StringVar(&opts.versionMigration, "version", "", "migrate the database to a specific version")
+	f.StringVar(&opts.migrationType, "type", "up", "type of migration (up, down) to be used with version flag")
 	return migrateApplyCmd
 }
 
@@ -46,11 +38,11 @@ type migrateApplyOptions struct {
 	upMigration      string
 	downMigration    string
 	versionMigration string
-	typeMigration    string
+	migrationType    string
 }
 
-func (o *migrateApplyOptions) Run() error {
-	migrationType, step, err := getMigrationTypeAndStep(o.upMigration, o.downMigration, o.versionMigration, o.typeMigration)
+func (o *migrateApplyOptions) run() error {
+	migrationType, step, err := getMigrationTypeAndStep(o.upMigration, o.downMigration, o.versionMigration, o.migrationType)
 	if err != nil {
 		return errors.Wrap(err, "error validating flags")
 	}
@@ -75,24 +67,25 @@ func (o *migrateApplyOptions) Run() error {
 	return nil
 }
 
-//Only one flag out of up,down and goto can be set at a time. This function checks whether that is the case and returns an error is not
-func getMigrationTypeAndStep(upMigration, downMigration, versionMigration, typeMigration string) (string, int64, error) {
+// Only one flag out of up, down and version can be set at a time. This function
+// checks whether that is the case and returns an error is not
+func getMigrationTypeAndStep(upMigration, downMigration, versionMigration, migrationType string) (string, int64, error) {
 	var flagCount = 0
 	var stepString = "all"
 	var migrationName = "up"
-	if upMigration != FLAG_NOT_SET {
+	if upMigration != "" {
 		stepString = upMigration
 		flagCount++
 	}
-	if downMigration != FLAG_NOT_SET {
+	if downMigration != "" {
 		migrationName = "down"
 		stepString = downMigration
 		flagCount++
 	}
-	if versionMigration != FLAG_NOT_SET {
+	if versionMigration != "" {
 		migrationName = "version"
 		stepString = versionMigration
-		if typeMigration != FLAG_NOT_SET {
+		if migrationType == "down" {
 			stepString = "-" + stepString
 		}
 		flagCount++
diff --git a/cli/commands/migrate_create.go b/cli/commands/migrate_create.go
@@ -9,7 +9,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
-func NewMigrateCreateCmd(ec *cli.ExecutionContext) *cobra.Command {
+func newMigrateCreateCmd(ec *cli.ExecutionContext) *cobra.Command {
 	opts := &migrateCreateOptions{
 		EC: ec,
 	}
@@ -22,7 +22,7 @@ func NewMigrateCreateCmd(ec *cli.ExecutionContext) *cobra.Command {
 		Args:         cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.name = args[0]
-			return opts.Run()
+			return opts.run()
 		},
 	}
 
@@ -35,7 +35,7 @@ type migrateCreateOptions struct {
 	name string
 }
 
-func (o *migrateCreateOptions) Run() error {
+func (o *migrateCreateOptions) run() error {
 	timestamp := getTime()
 	err := mig.CreateCmd(o.EC.MigrationDir, timestamp, o.name)
 	if err != nil {
diff --git a/cli/commands/migrate_status.go b/cli/commands/migrate_status.go
@@ -9,7 +9,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
-func NewMigrateStatusCmd(ec *cli.ExecutionContext) *cobra.Command {
+func newMigrateStatusCmd(ec *cli.ExecutionContext) *cobra.Command {
 	opts := &migrateStatusOptions{
 		EC: ec,
 	}
@@ -18,7 +18,7 @@ func NewMigrateStatusCmd(ec *cli.ExecutionContext) *cobra.Command {
 		Short:        "Display current status of migrations on a database",
 		SilenceUsage: true,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return opts.Run()
+			return opts.run()
 		},
 	}
 
@@ -29,7 +29,7 @@ type migrateStatusOptions struct {
 	EC *cli.ExecutionContext
 }
 
-func (o *migrateStatusOptions) Run() error {
+func (o *migrateStatusOptions) run() error {
 	dbURL, err := url.Parse(o.EC.Config.Endpoint)
 	if err != nil {
 		return errors.Wrap(err, "error parsing Endpoint")
diff --git a/cli/docs/hasura_migrate_apply.md b/cli/docs/hasura_migrate_apply.md
@@ -15,9 +15,9 @@ hasura migrate apply [flags]
 ```
       --down string      apply all or N down migration steps
   -h, --help             help for apply
-      --type string      migrate the database to a specific version specified by the timestamp
+      --type string      type of migration (up, down) to be used with version flag (default "up")
       --up string        apply all or N up migration steps
-      --version string   migrate the database to a specific version specified by the timestamp
+      --version string   migrate the database to a specific version
 ```
 
 ### Options inherited from parent commands
diff --git a/cli/migrate/migrate.go b/cli/migrate/migrate.go
@@ -1,3 +1,8 @@
+// Package migrate implements migrations on Hasura GraphQL Engine.
+//
+// This package is borrowed from https://github.com/golang-migrate/migrate with
+// additions for Hasura specific yaml file support and a improved Rails-like
+// migration pattern.
 package migrate
 
 import (
diff --git a/cli/util/download.go b/cli/util/download.go
@@ -6,6 +6,8 @@ import (
 	"os"
 )
 
+// Download downloads resource given by url and writes it to target.
+// target should not exist already, as it is created by the function.
 func Download(url, target string) error {
 	out, err := os.Create(target)
 	if err != nil {
diff --git a/cli/util/util.go b/cli/util/util.go
@@ -0,0 +1,2 @@
+// Package util contains utility functions used by various commands.
+package util
diff --git a/cli/util/zip.go b/cli/util/zip.go
@@ -7,8 +7,10 @@ import (
 	"path/filepath"
 )
 
-// https://gist.github.com/svett/424e6784facc0ba907ae
+// from  https://gist.github.com/svett/424e6784facc0ba907ae
 
+// Unzip unzips the archive to target. Both archive and target should be paths
+// in the filesystem. target is created if it doesn't exist already.
 func Unzip(archive, target string) error {
 	reader, err := zip.OpenReader(archive)
 	if err != nil {

Original file line number	Diff line number	Diff line change
`@@ -41,7 +41,7 @@ func NewInitCmd(ec cli.ExecutionContext) cobra.Command {`
`41`	`41`	`return ec.Prepare()`
`42`	`42`	`},`
`43`	`43`	`RunE: func(cmd *cobra.Command, args []string) error {`
`44`		`- return opts.Run()`
	`44`	`+ return opts.run()`
`45`	`45`	`},`
`46`	`46`	`}`
`47`	`47`
`@@ -60,7 +60,7 @@ type initOptions struct {`
`60`	`60`	`InitDir string`
`61`	`61`	`}`
`62`	`62`
`63`		`-func (o *initOptions) Run() error {`
	`63`	`+func (o *initOptions) run() error {`
`64`	`64`	`if o.EC.ExecutionDirectory == "" {`
`65`	`65`	`o.EC.ExecutionDirectory = o.InitDir`
`66`	`66`	`}`
Original file line number	Diff line number	Diff line change
`@@ -18,9 +18,9 @@ func NewMetadataCmd(ec cli.ExecutionContext) cobra.Command {`
`18`	`18`	`},`
`19`	`19`	`}`
`20`	`20`	`metadataCmd.AddCommand(`
`21`		`- NewMetadataExportCmd(ec),`
`22`		`- NewMetadataResetCmd(ec),`
`23`		`- NewMetadataApplyCmd(ec),`
	`21`	`+ newMetadataExportCmd(ec),`
	`22`	`+ newMetadataResetCmd(ec),`
	`23`	`+ newMetadataApplyCmd(ec),`
`24`	`24`	`)`
`25`	`25`	`f := metadataCmd.PersistentFlags()`
`26`	`26`	`f.String("endpoint", "", "http(s) endpoint for Hasura GraphQL Engine")`
Original file line number	Diff line number	Diff line change
`@@ -20,9 +20,9 @@ func NewMigrateCmd(ec cli.ExecutionContext) cobra.Command {`
`20`	`20`	`},`
`21`	`21`	`}`
`22`	`22`	`migrateCmd.AddCommand(`
`23`		`- NewMigrateApplyCmd(ec),`
`24`		`- NewMigrateStatusCmd(ec),`
`25`		`- NewMigrateCreateCmd(ec),`
	`23`	`+ newMigrateApplyCmd(ec),`
	`24`	`+ newMigrateStatusCmd(ec),`
	`25`	`+ newMigrateCreateCmd(ec),`
`26`	`26`	`)`
`27`	`27`	`f := migrateCmd.PersistentFlags()`
`28`	`28`	`f.String("endpoint", "", "http(s) endpoint for Hasura GraphQL Engine")`
Original file line number	Diff line number	Diff line change
`@@ -9,7 +9,7 @@ import (`
`9`	`9`	`"github.com/spf13/cobra"`
`10`	`10`	`)`
`11`	`11`
`12`		`-func NewMigrateCreateCmd(ec cli.ExecutionContext) cobra.Command {`
	`12`	`+func newMigrateCreateCmd(ec cli.ExecutionContext) cobra.Command {`
`13`	`13`	`opts := &migrateCreateOptions{`
`14`	`14`	`EC: ec,`
`15`	`15`	`}`
`@@ -22,7 +22,7 @@ func NewMigrateCreateCmd(ec cli.ExecutionContext) cobra.Command {`
`22`	`22`	`Args: cobra.ExactArgs(1),`
`23`	`23`	`RunE: func(cmd *cobra.Command, args []string) error {`
`24`	`24`	`opts.name = args[0]`
`25`		`- return opts.Run()`
	`25`	`+ return opts.run()`
`26`	`26`	`},`
`27`	`27`	`}`
`28`	`28`
`@@ -35,7 +35,7 @@ type migrateCreateOptions struct {`
`35`	`35`	`name string`
`36`	`36`	`}`
`37`	`37`
`38`		`-func (o *migrateCreateOptions) Run() error {`
	`38`	`+func (o *migrateCreateOptions) run() error {`
`39`	`39`	`timestamp := getTime()`
`40`	`40`	`err := mig.CreateCmd(o.EC.MigrationDir, timestamp, o.name)`
`41`	`41`	`if err != nil {`