docs: make code comments more informative

Author: hazadus

cmd/commitmsg/main.go

@@ -1,4 +1,4 @@
-// CLI tool to get staged changes in a git repository and print them to the console
+// CLI tool to generate AI-powered commit messages based on staged changes.
 package main
 
 import (
@@ -48,8 +48,9 @@ func runCommitMsg(_ *cobra.Command, _ []string) error {
 		return nil
 	}
 
+	// Add examples of previous commit messages to context if the flag is set
 	latestCommitMessages := ""
-	if flagExamples{
+	if flagExamples {
 		latestCommitMessages, err = git.GetCommitMessages(3)
 		if err != nil {
 			return fmt.Errorf("failed to get latest commit messages: %w", err)

internal/git/git.go

@@ -6,7 +6,7 @@ import (
 	"os/exec"
 )
 
-// GetStagedChanges executes the command git diff --staged and returns its output
+// GetStainedChanges returns the staged changes (git diff --staged) as a string.
 func GetStagedChanges() (string, error) {
 	// Check if we are in a git repository
 	if !isGitRepository() {
@@ -23,7 +23,7 @@ func GetStagedChanges() (string, error) {
 	return string(output), nil
 }
 
-// GetCommitMessages retrieves the last <count> commit messages from the git repository
+// GetCommitMessages retrieves the last <count> commit messages from the git repository.
 func GetCommitMessages(count int) (string, error) {
 	// Check if we are in a git repository
 	if !isGitRepository() {

internal/llm/client.go

@@ -18,28 +18,27 @@ import (
 //go:embed commitmsg.prompt.yml
 var commitmsgPromptYAML []byte
 
-// PromptConfig represents the structure of the prompt configuration file
-// It includes the model parameters and the messages to be sent to the model.
+// PromptConfig represents the structure of the prompt configuration file.
 type PromptConfig struct {
 	Name            string          `yaml:"name"`
 	Description     string          `yaml:"description"`
 	ModelParameters ModelParameters `yaml:"modelParameters"`
 	Messages        []PromptMessage `yaml:"messages"`
 }
 
-// ModelParameters defines the parameters for the model
+// ModelParameters defines the parameters for the large language model.
 type ModelParameters struct {
 	Temperature float64 `yaml:"temperature"`
 	TopP        float64 `yaml:"topP"`
 }
 
-// PromptMessage represents a single message in the prompt configuration
+// PromptMessage represents a single message in the prompt configuration.
 type PromptMessage struct {
 	Role    string `yaml:"role"`
 	Content string `yaml:"content"`
 }
 
-// Request represents the structure of the request to the GitHub Models API
+// Request represents the request payload for the GitHub Models API.
 type Request struct {
 	Messages    []Message `json:"messages"`
 	Model       string    `json:"model"`
@@ -48,13 +47,13 @@ type Request struct {
 	Stream      bool      `json:"stream"`
 }
 
-// Message represents a single message in the request to the GitHub Models API
+// Message represents a single message in the request payload.
 type Message struct {
 	Role    string `json:"role"`
 	Content string `json:"content"`
 }
 
-// Response represents the structure of the response from the GitHub Models API
+// Response represents the response payload from the GitHub Models API.
 type Response struct {
 	Choices []struct {
 		Message struct {
@@ -68,8 +67,8 @@ type Client struct {
 	token string
 }
 
-// NewClient initializes a new GitHub Models API client
-// It retrieves the GitHub token from the environment installed by the `gh` CLI tool.
+// NewClient initializes a new GitHub Models API client.
+// It retrieves the GitHub token using gh auth token command.
 func NewClient() (*Client, error) {
 	fmt.Print("  Checking GitHub token... ")
 
@@ -100,6 +99,7 @@ func (c *Client) GenerateCommitMessage(
 	}
 	fmt.Println("Done")
 
+	// Build messages from the prompt config, replacing template variables
 	selectedModel := model
 	selectedLanguage := language
 
@@ -125,6 +125,7 @@ func (c *Client) GenerateCommitMessage(
 		}
 	}
 
+	// Prepare the request for the GitHub Models API
 	request := Request{
 		Messages:    messages,
 		Model:       selectedModel,
@@ -141,6 +142,7 @@ func (c *Client) GenerateCommitMessage(
 	}
 	fmt.Println("Done")
 
+	// Extract the generated commit message from the response
 	if len(response.Choices) == 0 {
 		return "", fmt.Errorf("no response generated from the model")
 	}