devbox: docs and some cleanup (#2645)

Add package docs and tweak a few things to follow some Go idioms.

- Use regular casing for constants.
- Rename `Init` to `InitConfig`. Although the signature isn't the same,
  `Init` is very close the special package init function.
- Put Open directly under the Devbox struct.

Author: gcurtis

boxcli/init.go

@@ -21,7 +21,7 @@ func InitCmd() *cobra.Command {
 func runInitCmd(cmd *cobra.Command, args []string) error {
 	path := pathArg(args)
 
-	_, err := devbox.Init(path)
+	_, err := devbox.InitConfig(path)
 	if err != nil {
 		return errors.WithStack(err)
 	}

config.go

@@ -8,10 +8,14 @@ import (
 	"go.jetpack.io/devbox/cuecfg"
 )
 
+// Config defines a devbox environment as JSON.
 type Config struct {
+	// Packages is the slice of Nix packages that devbox makes available in
+	// its environment.
 	Packages []string `cue:"[...string]" json:"packages,omitempty"`
 }
 
+// ReadConfig reads a devbox config file.
 func ReadConfig(path string) (*Config, error) {
 	cfg := &Config{}
 	err := cuecfg.ReadFile(path, cfg)
@@ -21,6 +25,7 @@ func ReadConfig(path string) (*Config, error) {
 	return cfg, nil
 }
 
+// WriteConfig saves a devbox config file.
 func WriteConfig(path string, cfg *Config) error {
 	return cuecfg.WriteFile(path, cfg)
 }

devbox.go

@@ -1,6 +1,7 @@
 // Copyright 2022 Jetpack Technologies Inc and contributors. All rights reserved.
 // Use of this source code is governed by the license in the LICENSE file.
 
+// Package devbox creates isolated development environments.
 package devbox
 
 import (
@@ -14,20 +15,26 @@ import (
 	"go.jetpack.io/devbox/planner"
 )
 
+// configFilename is name of the JSON file that defines a devbox environment.
+const configFilename = "devbox.json"
+
+// InitConfig creates a default devbox config file if one doesn't already
+// exist.
+func InitConfig(dir string) (created bool, err error) {
+	cfgPath := filepath.Join(dir, configFilename)
+	return cuecfg.InitFile(cfgPath, &Config{})
+}
+
+// Devbox provides an isolated development environment that contains a set of
+// Nix packages.
 type Devbox struct {
 	cfg    *Config
 	srcDir string
 }
 
-const CONFIG_FILENAME = "devbox.json"
-
-func Init(dir string) (bool, error) {
-	cfgPath := filepath.Join(dir, CONFIG_FILENAME)
-	return cuecfg.InitFile(cfgPath, &Config{})
-}
-
+// Open opens a devbox by reading the config file in dir.
 func Open(dir string) (*Devbox, error) {
-	cfgPath := filepath.Join(dir, CONFIG_FILENAME)
+	cfgPath := filepath.Join(dir, configFilename)
 
 	cfg, err := ReadConfig(cfgPath)
 	if err != nil {
@@ -41,30 +48,32 @@ func Open(dir string) (*Devbox, error) {
 	return box, nil
 }
 
+// Add adds a Nix package to the config so that it's available in the devbox
+// environment. It validates that the Nix package exists, but doesn't install
+// it. Adding a duplicate package is a no-op.
 func (d *Devbox) Add(pkgs ...string) error {
 	// Check packages exist before adding.
 	for _, pkg := range pkgs {
 		ok := nix.PkgExists(pkg)
 		if !ok {
-			return errors.Errorf("Package %s not found.", pkg)
+			return errors.Errorf("package %s not found", pkg)
 		}
 	}
 	// Merge and remove duplicates:
 	merged := append(d.cfg.Packages, pkgs...)
 	d.cfg.Packages = lo.FindUniques(merged)
-
-	// Save config.
 	return d.saveCfg()
 }
 
+// Remove removes Nix packages from the config so that it no longer exists in
+// the devbox environment.
 func (d *Devbox) Remove(pkgs ...string) error {
 	// Remove packages from config.
 	d.cfg.Packages = lo.Without(d.cfg.Packages, pkgs...)
-
-	// Save config.
 	return d.saveCfg()
 }
 
+// Build creates a Docker image containing a shell with the devbox environment.
 func (d *Devbox) Build(opts ...docker.BuildOptions) error {
 	defaultFlags := &docker.BuildFlags{
 		Name:           "devbox",
@@ -79,18 +88,24 @@ func (d *Devbox) Build(opts ...docker.BuildOptions) error {
 	return docker.Build(d.srcDir, opts...)
 }
 
+// Plan creates a plan of the actions that devbox will take to generate its
+// environment.
 func (d *Devbox) Plan() *planner.BuildPlan {
 	basePlan := &planner.BuildPlan{
 		Packages: d.cfg.Packages,
 	}
 	return planner.MergePlans(basePlan, planner.Plan(d.srcDir))
 }
 
+// Generate creates the directory of Nix files and the Dockerfile that define
+// the devbox environment.
 func (d *Devbox) Generate() error {
 	plan := d.Plan()
 	return generate(d.srcDir, plan)
 }
 
+// Shell generates the devbox environment and launches nix-shell as a child
+// process.
 func (d *Devbox) Shell() error {
 	err := d.Generate()
 	if err != nil {
@@ -100,7 +115,8 @@ func (d *Devbox) Shell() error {
 	return nix.Shell(nixDir)
 }
 
+// saveCfg writes the config file to the devbox directory.
 func (d *Devbox) saveCfg() error {
-	cfgPath := filepath.Join(d.srcDir, CONFIG_FILENAME)
+	cfgPath := filepath.Join(d.srcDir, configFilename)
 	return cuecfg.WriteFile(cfgPath, d.cfg)
 }