Update documentation

server/internal/storage/files.go

@@ -30,12 +30,7 @@ type FileNode struct {
 }
 
 // ListFilesRecursively returns a list of all files in the workspace directory and its subdirectories.
-// Parameters:
-// - userID: the ID of the user who owns the workspace
-// - workspaceID: the ID of the workspace to list files in
-// Returns:
-// - nodes: a list of files and directories in the workspace
-// - error: any error that occurred during listing
+// Workspace is identified by the given userID and workspaceID.
 func (s *Service) ListFilesRecursively(userID, workspaceID int) ([]FileNode, error) {
 	workspacePath := s.GetWorkspacePath(userID, workspaceID)
 	return s.walkDirectory(workspacePath, "")
@@ -106,13 +101,8 @@ func (s *Service) walkDirectory(dir, prefix string) ([]FileNode, error) {
 }
 
 // FindFileByName returns a list of file paths that match the given filename.
-// Parameters:
-// - userID: the ID of the user who owns the workspace
-// - workspaceID: the ID of the workspace to search for the file
-// - filename: the name of the file to search for
-// Returns:
-// - foundPaths: a list of file paths that match the filename
-// - error: any error that occurred during the search
+// Files are searched recursively in the workspace directory and its subdirectories.
+// Workspace is identified by the given userID and workspaceID.
 func (s *Service) FindFileByName(userID, workspaceID int, filename string) ([]string, error) {
 	var foundPaths []string
 	workspacePath := s.GetWorkspacePath(userID, workspaceID)
@@ -144,14 +134,8 @@ func (s *Service) FindFileByName(userID, workspaceID int, filename string) ([]st
 	return foundPaths, nil
 }
 
-// GetFileContent returns the content of the file at the given path.
-// Parameters:
-// - userID: the ID of the user who owns the workspace
-// - workspaceID: the ID of the workspace to get the file from
-// - filePath: the path of the file to get
-// Returns:
-// - content: the content of the file
-// - error: any error that occurred during reading
+// GetFileContent returns the content of the file at the given filePath.
+// Path must be a relative path within the workspace directory given by userID and workspaceID.
 func (s *Service) GetFileContent(userID, workspaceID int, filePath string) ([]byte, error) {
 	fullPath, err := s.ValidatePath(userID, workspaceID, filePath)
 	if err != nil {
@@ -160,14 +144,8 @@ func (s *Service) GetFileContent(userID, workspaceID int, filePath string) ([]by
 	return s.fs.ReadFile(fullPath)
 }
 
-// SaveFile writes the content to the file at the given path.
-// Parameters:
-// - userID: the ID of the user who owns the workspace
-// - workspaceID: the ID of the workspace to save the file to
-// - filePath: the path of the file to save
-// - content: the content to write to the file
-// Returns:
-// - error: any error that occurred during saving
+// SaveFile writes the content to the file at the given filePath.
+// Path must be a relative path within the workspace directory given by userID and workspaceID.
 func (s *Service) SaveFile(userID, workspaceID int, filePath string, content []byte) error {
 	fullPath, err := s.ValidatePath(userID, workspaceID, filePath)
 	if err != nil {
@@ -182,13 +160,8 @@ func (s *Service) SaveFile(userID, workspaceID int, filePath string, content []b
 	return s.fs.WriteFile(fullPath, content, 0644)
 }
 
-// DeleteFile deletes the file at the given path.
-// Parameters:
-// - userID: the ID of the user who owns the workspace
-// - workspaceID: the ID of the workspace to delete the file from
-// - filePath: the path of the file to delete
-// Returns:
-// - error: any error that occurred during deletion
+// DeleteFile deletes the file at the given filePath.
+// Path must be a relative path within the workspace directory given by userID and workspaceID.
 func (s *Service) DeleteFile(userID, workspaceID int, filePath string) error {
 	fullPath, err := s.ValidatePath(userID, workspaceID, filePath)
 	if err != nil {
@@ -204,12 +177,7 @@ type FileCountStats struct {
 }
 
 // GetFileStats returns the total number of files and related statistics in a workspace
-// Parameters:
-// - userID: the ID of the user who owns the workspace
-// - workspaceID: the ID of the workspace to count files in
-// Returns:
-// - result: statistics about the files in the workspace
-// - error: any error that occurred during counting
+// Workspace is identified by the given userID and workspaceID
 func (s *Service) GetFileStats(userID, workspaceID int) (*FileCountStats, error) {
 	workspacePath := s.GetWorkspacePath(userID, workspaceID)
 
@@ -223,8 +191,6 @@ func (s *Service) GetFileStats(userID, workspaceID int) (*FileCountStats, error)
 }
 
 // GetTotalFileStats returns the total file statistics for the storage.
-// Returns:
-// - result: statistics about the files in the storage
 func (s *Service) GetTotalFileStats() (*FileCountStats, error) {
 	return s.countFilesInPath(s.RootDir)
 }

server/internal/storage/git.go

@@ -13,15 +13,8 @@ type RepositoryManager interface {
 	Pull(userID, workspaceID int) error
 }
 
-// SetupGitRepo sets up a Git repository for the given user and workspace IDs.
-// Parameters:
-// - userID: the ID of the user who owns the workspace
-// - workspaceID: the ID of the workspace to set up the Git repository for
-// - gitURL: the URL of the Git repository
-// - gitUser: the username for the Git repository
-// - gitToken: the access token for the Git repository
-// Returns:
-// - error: any error that occurred during setup
+// SetupGitRepo sets up a Git repository for the given userID and workspaceID.
+// The repository is cloned from the given gitURL using the given gitUser and gitToken.
 func (s *Service) SetupGitRepo(userID, workspaceID int, gitURL, gitUser, gitToken string) error {
 	workspacePath := s.GetWorkspacePath(userID, workspaceID)
 	if _, ok := s.GitRepos[userID]; !ok {
@@ -31,10 +24,7 @@ func (s *Service) SetupGitRepo(userID, workspaceID int, gitURL, gitUser, gitToke
 	return s.GitRepos[userID][workspaceID].EnsureRepo()
 }
 
-// DisableGitRepo disables the Git repository for the given user and workspace IDs.
-// Parameters:
-// - userID: the ID of the user who owns the workspace
-// - workspaceID: the ID of the workspace to disable the Git repository for
+// DisableGitRepo disables the Git repository for the given userID and workspaceID.
 func (s *Service) DisableGitRepo(userID, workspaceID int) {
 	if userRepos, ok := s.GitRepos[userID]; ok {
 		delete(userRepos, workspaceID)
@@ -44,13 +34,8 @@ func (s *Service) DisableGitRepo(userID, workspaceID int) {
 	}
 }
 
-// StageCommitAndPush stages, commits, and pushes the changes to the Git repository.
-// Parameters:
-// - userID: the ID of the user who owns the workspace
-// - workspaceID: the ID of the workspace to commit and push
-// - message: the commit message
-// Returns:
-// - error: any error that occurred during the operation
+// StageCommitAndPush stages, commit with the message, and pushes the changes to the Git repository.
+// The git repository belongs to the given userID and is associated with the given workspaceID.
 func (s *Service) StageCommitAndPush(userID, workspaceID int, message string) error {
 	repo, ok := s.getGitRepo(userID, workspaceID)
 	if !ok {
@@ -65,11 +50,7 @@ func (s *Service) StageCommitAndPush(userID, workspaceID int, message string) er
 }
 
 // Pull pulls the changes from the remote Git repository.
-// Parameters:
-// - userID: the ID of the user who owns the workspace
-// - workspaceID: the ID of the workspace to pull changes for
-// Returns:
-// - error: any error that occurred during the operation
+// The git repository belongs to the given userID and is associated with the given workspaceID.
 func (s *Service) Pull(userID, workspaceID int) error {
 	repo, ok := s.getGitRepo(userID, workspaceID)
 	if !ok {

server/internal/storage/service.go

@@ -25,11 +25,7 @@ type Options struct {
 	NewGitClient func(url, user, token, path string) git.Client
 }
 
-// NewService creates a new Storage instance.
-// Parameters:
-// - rootDir: the root directory for the storage
-// Returns:
-// - result: the new Storage instance
+// NewService creates a new Storage instance with the default options and the given rootDir root directory.
 func NewService(rootDir string) *Service {
 	return NewServiceWithOptions(rootDir, Options{
 		Fs:           &osFS{},
@@ -37,16 +33,11 @@ func NewService(rootDir string) *Service {
 	})
 }
 
-// NewServiceWithOptions creates a new Storage instance with the given options.
-// Parameters:
-// - rootDir: the root directory for the storage
-// - opts: the options for the storage service
-// Returns:
-// - result: the new Storage instance
-func NewServiceWithOptions(rootDir string, opts Options) *Service {
+// NewServiceWithOptions creates a new Storage instance with the given options and the given rootDir root directory.
+func NewServiceWithOptions(rootDir string, options Options) *Service {
 	return &Service{
-		fs:           opts.Fs,
-		newGitClient: opts.NewGitClient,
+		fs:           options.Fs,
+		newGitClient: options.NewGitClient,
 		RootDir:      rootDir,
 		GitRepos:     make(map[int]map[int]git.Client),
 	}

server/internal/storage/workspace.go

@@ -14,14 +14,8 @@ type WorkspaceManager interface {
 	DeleteUserWorkspace(userID, workspaceID int) error
 }
 
-// ValidatePath validates the given path and returns the cleaned path if it is valid.
-// Parameters:
-// - userID: the ID of the user who owns the workspace
-// - workspaceID: the ID of the workspace to validate the path for
-// - path: the path to validate
-// Returns:
-// - result: the cleaned path if it is valid
-// - error: any error that occurred during validation
+// ValidatePath validates the if the given path is valid within the workspace directory.
+// Workspace directory is defined as the directory for the given userID and workspaceID.
 func (s *Service) ValidatePath(userID, workspaceID int, path string) (string, error) {
 	workspacePath := s.GetWorkspacePath(userID, workspaceID)
 
@@ -42,22 +36,12 @@ func (s *Service) ValidatePath(userID, workspaceID int, path string) (string, er
 	return cleanPath, nil
 }
 
-// GetWorkspacePath returns the path to the workspace directory for the given user and workspace IDs.
-// Parameters:
-// - userID: the ID of the user who owns the workspace
-// - workspaceID: the ID of the workspace
-// Returns:
-// - result: the path to the workspace directory
+// GetWorkspacePath returns the path to the workspace directory for the given userID and workspaceID.
 func (s *Service) GetWorkspacePath(userID, workspaceID int) string {
 	return filepath.Join(s.RootDir, fmt.Sprintf("%d", userID), fmt.Sprintf("%d", workspaceID))
 }
 
-// InitializeUserWorkspace creates the workspace directory for the given user and workspace IDs.
-// Parameters:
-// - userID: the ID of the user who owns the workspace
-// - workspaceID: the ID of the workspace to initialize
-// Returns:
-// - error: any error that occurred during the operation
+// InitializeUserWorkspace creates the workspace directory for the given userID and workspaceID.
 func (s *Service) InitializeUserWorkspace(userID, workspaceID int) error {
 	workspacePath := s.GetWorkspacePath(userID, workspaceID)
 	err := s.fs.MkdirAll(workspacePath, 0755)
@@ -68,12 +52,7 @@ func (s *Service) InitializeUserWorkspace(userID, workspaceID int) error {
 	return nil
 }
 
-// DeleteUserWorkspace deletes the workspace directory for the given user and workspace IDs.
-// Parameters:
-// - userID: the ID of the user who owns the workspace
-// - workspaceID: the ID of the workspace to delete
-// Returns:
-// - error: any error that occurred during the operation
+// DeleteUserWorkspace deletes the workspace directory for the given userID and workspaceID.
 func (s *Service) DeleteUserWorkspace(userID, workspaceID int) error {
 	workspacePath := s.GetWorkspacePath(userID, workspaceID)
 	err := s.fs.RemoveAll(workspacePath)