more documentation

pkg/gui/app_status_manager.go

@@ -8,18 +8,20 @@ import (
 	"github.com/jesseduffield/lazygit/pkg/utils"
 )
 
-type appStatus struct {
-	message    string
-	statusType string
-	id         int
-}
-
+// statusManager's job is to handle rendering of loading states and toast notifications
+// that you see at the bottom left of the screen.
 type statusManager struct {
 	statuses []appStatus
 	nextId   int
 	mutex    sync.Mutex
 }
 
+type appStatus struct {
+	message    string
+	statusType string
+	id         int
+}
+
 func (m *statusManager) removeStatus(id int) {
 	m.mutex.Lock()
 	defer m.mutex.Unlock()

pkg/gui/arrangement.go

@@ -7,6 +7,9 @@ import (
 	"github.com/jesseduffield/lazygit/pkg/utils"
 )
 
+// In this file we use the boxlayout package, along with knowledge about the app's state,
+// to arrange the windows (i.e. panels) on the screen.
+
 const INFO_SECTION_PADDING = " "
 
 func (gui *Gui) mainSectionChildren() []*boxlayout.Box {

pkg/gui/confirmation_panel.go

@@ -12,6 +12,9 @@ import (
 	"github.com/jesseduffield/lazygit/pkg/utils"
 )
 
+// This file is for the rendering of confirmation panels along with setting and handling associated
+// keybindings.
+
 func (gui *Gui) wrappedConfirmationFunction(handlersManageFocus bool, function func() error) func() error {
 	return func() error {
 		if err := gui.closeConfirmationPrompt(handlersManageFocus); err != nil {

pkg/gui/context.go

@@ -13,6 +13,11 @@ import (
 	"github.com/jesseduffield/lazygit/pkg/gui/types"
 )
 
+// This file is for the management of contexts. There is a context stack such that
+// for example you might start off in the commits context and then open a menu, putting
+// you in the menu context. When contexts are activated/deactivated certain things need
+// to happen like showing/hiding views and rendering content.
+
 func (gui *Gui) popupViewNames() []string {
 	popups := slices.Filter(gui.State.Contexts.Flatten(), func(c types.Context) bool {
 		return c.GetKind() == types.PERSISTENT_POPUP || c.GetKind() == types.TEMPORARY_POPUP

pkg/gui/lbl/state.go

@@ -5,6 +5,9 @@ import (
 	"github.com/sirupsen/logrus"
 )
 
+// State represents the current state of the line-by-line context i.e. when
+// you're staging a file line-by-line or you're building a patch from an existing commit
+// this struct holds the info about the diff you're interacting with and what's currently selected.
 type State struct {
 	selectedLineIdx   int
 	rangeStartLineIdx int

pkg/gui/mergeconflicts/state.go

@@ -6,6 +6,7 @@ import (
 	"github.com/jesseduffield/lazygit/pkg/utils"
 )
 
+// State represents the selection state of the merge conflict context.
 type State struct {
 	sync.Mutex
 

pkg/gui/popup/fake_popup_handler.go

@@ -0,0 +1,51 @@
+package popup
+
+import "github.com/jesseduffield/lazygit/pkg/gui/types"
+
+type FakePopupHandler struct {
+	OnErrorMsg func(message string) error
+	OnConfirm  func(opts types.ConfirmOpts) error
+	OnPrompt   func(opts types.PromptOpts) error
+}
+
+var _ types.IPopupHandler = &FakePopupHandler{}
+
+func (self *FakePopupHandler) Error(err error) error {
+	return self.ErrorMsg(err.Error())
+}
+
+func (self *FakePopupHandler) ErrorMsg(message string) error {
+	return self.OnErrorMsg(message)
+}
+
+func (self *FakePopupHandler) Alert(title string, message string) error {
+	panic("not yet implemented")
+}
+
+func (self *FakePopupHandler) Confirm(opts types.ConfirmOpts) error {
+	return self.Confirm(opts)
+}
+
+func (self *FakePopupHandler) Prompt(opts types.PromptOpts) error {
+	return self.OnPrompt(opts)
+}
+
+func (self *FakePopupHandler) WithLoaderPanel(message string, f func() error) error {
+	return f()
+}
+
+func (self *FakePopupHandler) WithWaitingStatus(message string, f func() error) error {
+	return f()
+}
+
+func (self *FakePopupHandler) Menu(opts types.CreateMenuOptions) error {
+	panic("not yet implemented")
+}
+
+func (self *FakePopupHandler) Toast(message string) {
+	panic("not yet implemented")
+}
+
+func (self *FakePopupHandler) GetPromptInput() string {
+	panic("not yet implemented")
+}

pkg/gui/popup/popup_handler.go

@@ -11,7 +11,7 @@ import (
 	"github.com/jesseduffield/lazygit/pkg/utils"
 )
 
-type RealPopupHandler struct {
+type PopupHandler struct {
 	*common.Common
 	index int
 	sync.Mutex
@@ -24,7 +24,7 @@ type RealPopupHandler struct {
 	getPromptInputFn    func() string
 }
 
-var _ types.IPopupHandler = &RealPopupHandler{}
+var _ types.IPopupHandler = &PopupHandler{}
 
 func NewPopupHandler(
 	common *common.Common,
@@ -35,8 +35,8 @@ func NewPopupHandler(
 	withWaitingStatusFn func(message string, f func() error) error,
 	toastFn func(message string),
 	getPromptInputFn func() string,
-) *RealPopupHandler {
-	return &RealPopupHandler{
+) *PopupHandler {
+	return &PopupHandler{
 		Common:              common,
 		index:               0,
 		createPopupPanelFn:  createPopupPanelFn,
@@ -49,19 +49,19 @@ func NewPopupHandler(
 	}
 }
 
-func (self *RealPopupHandler) Menu(opts types.CreateMenuOptions) error {
+func (self *PopupHandler) Menu(opts types.CreateMenuOptions) error {
 	return self.createMenuFn(opts)
 }
 
-func (self *RealPopupHandler) Toast(message string) {
+func (self *PopupHandler) Toast(message string) {
 	self.toastFn(message)
 }
 
-func (self *RealPopupHandler) WithWaitingStatus(message string, f func() error) error {
+func (self *PopupHandler) WithWaitingStatus(message string, f func() error) error {
 	return self.withWaitingStatusFn(message, f)
 }
 
-func (self *RealPopupHandler) Error(err error) error {
+func (self *PopupHandler) Error(err error) error {
 	if err == gocui.ErrQuit {
 		return err
 	}
@@ -69,7 +69,7 @@ func (self *RealPopupHandler) Error(err error) error {
 	return self.ErrorMsg(err.Error())
 }
 
-func (self *RealPopupHandler) ErrorMsg(message string) error {
+func (self *PopupHandler) ErrorMsg(message string) error {
 	self.Lock()
 	self.index++
 	self.Unlock()
@@ -83,11 +83,11 @@ func (self *RealPopupHandler) ErrorMsg(message string) error {
 	return self.Alert(self.Tr.Error, coloredMessage)
 }
 
-func (self *RealPopupHandler) Alert(title string, message string) error {
+func (self *PopupHandler) Alert(title string, message string) error {
 	return self.Confirm(types.ConfirmOpts{Title: title, Prompt: message})
 }
 
-func (self *RealPopupHandler) Confirm(opts types.ConfirmOpts) error {
+func (self *PopupHandler) Confirm(opts types.ConfirmOpts) error {
 	self.Lock()
 	self.index++
 	self.Unlock()
@@ -101,7 +101,7 @@ func (self *RealPopupHandler) Confirm(opts types.ConfirmOpts) error {
 	})
 }
 
-func (self *RealPopupHandler) Prompt(opts types.PromptOpts) error {
+func (self *PopupHandler) Prompt(opts types.PromptOpts) error {
 	self.Lock()
 	self.index++
 	self.Unlock()
@@ -117,7 +117,7 @@ func (self *RealPopupHandler) Prompt(opts types.PromptOpts) error {
 	})
 }
 
-func (self *RealPopupHandler) WithLoaderPanel(message string, f func() error) error {
+func (self *PopupHandler) WithLoaderPanel(message string, f func() error) error {
 	index := 0
 	self.Lock()
 	self.index++
@@ -150,54 +150,6 @@ func (self *RealPopupHandler) WithLoaderPanel(message string, f func() error) er
 
 // returns the content that has currently been typed into the prompt. Useful for
 // asynchronously updating the suggestions list under the prompt.
-func (self *RealPopupHandler) GetPromptInput() string {
+func (self *PopupHandler) GetPromptInput() string {
 	return self.getPromptInputFn()
 }
-
-type TestPopupHandler struct {
-	OnErrorMsg func(message string) error
-	OnConfirm  func(opts types.ConfirmOpts) error
-	OnPrompt   func(opts types.PromptOpts) error
-}
-
-var _ types.IPopupHandler = &TestPopupHandler{}
-
-func (self *TestPopupHandler) Error(err error) error {
-	return self.ErrorMsg(err.Error())
-}
-
-func (self *TestPopupHandler) ErrorMsg(message string) error {
-	return self.OnErrorMsg(message)
-}
-
-func (self *TestPopupHandler) Alert(title string, message string) error {
-	panic("not yet implemented")
-}
-
-func (self *TestPopupHandler) Confirm(opts types.ConfirmOpts) error {
-	return self.Confirm(opts)
-}
-
-func (self *TestPopupHandler) Prompt(opts types.PromptOpts) error {
-	return self.OnPrompt(opts)
-}
-
-func (self *TestPopupHandler) WithLoaderPanel(message string, f func() error) error {
-	return f()
-}
-
-func (self *TestPopupHandler) WithWaitingStatus(message string, f func() error) error {
-	return f()
-}
-
-func (self *TestPopupHandler) Menu(opts types.CreateMenuOptions) error {
-	panic("not yet implemented")
-}
-
-func (self *TestPopupHandler) Toast(message string) {
-	panic("not yet implemented")
-}
-
-func (self *TestPopupHandler) GetPromptInput() string {
-	panic("not yet implemented")
-}

pkg/integration/integration.go

@@ -18,6 +18,8 @@ import (
 	"github.com/jesseduffield/lazygit/pkg/secureexec"
 )
 
+// This package is for running our integration test suite. See docs/Integration_Tests.md for more info
+
 type Test struct {
 	Name         string  `json:"name"`
 	Speed        float64 `json:"speed"`

pkg/tasks/tasks.go

@@ -14,6 +14,14 @@ import (
 	"github.com/sirupsen/logrus"
 )
 
+// This file revolves around running commands that will be output to the main panel
+// in the gui. If we're flicking through the commits panel, we want to invoke a
+// `git show` command for each commit, but we don't want to read the entire output
+// at once (because that would slow things down); we just want to fill the panel
+// and then read more as the user scrolls down. We also want to ensure that we're only
+// ever running one `git show` command at time, and that we only have one command
+// writing its output to the main panel at a time.
+
 const THROTTLE_TIME = time.Millisecond * 30
 
 // we use this to check if the system is under stress right now. Hopefully this makes sense on other machines
@@ -26,7 +34,6 @@ type ViewBufferManager struct {
 	// this is what we write the output of the task to. It's typically a view
 	writer io.Writer
 
-	// this is for when we wait to get
 	waitingMutex sync.Mutex
 	taskIDMutex  sync.Mutex
 	Log          *logrus.Entry

test/lazyintegration/main.go

@@ -14,7 +14,7 @@ import (
 	"github.com/jesseduffield/lazygit/pkg/secureexec"
 )
 
-// this program lets you manage integration tests in a TUI.
+// this program lets you manage integration tests in a TUI. See docs/Integration_Tests.md for more info.
 
 type App struct {
 	tests   []*integration.Test

test/runner/main.go

@@ -11,7 +11,7 @@ import (
 	"github.com/stretchr/testify/assert"
 )
 
-// see https://github.com/jesseduffield/lazygit/blob/master/docs/Integration_Tests.md
+// see docs/Integration_Tests.md
 // This file can be invoked directly, but you might find it easier to go through
 // test/lazyintegration/main.go, which provides a convenient gui wrapper to integration tests.
 //