Task: Generated Code Comments for MeTTa in LSP Server

[TeamSPoon]

I know whis was a task but dont think I ever created an issue until now...

Overview

We are extending our LSP (Language Server Protocol) server to support generated comments for MeTTa code. When a user requests comments, the LSP server will invoke an LLM (Large Language Model) to analyze the code and generate meaningful explanations. The comments should follow MeTTa’s syntax, using ; for single-line comments. The system should insert these comments appropriately without altering the semantics of the code.

Objectives

• Implement an LSP feature that allows users to request LLM-generated comments in MeTTa.
• Ensure the comments are syntactically correct (using ; for single-line comments).
• Integrate the feature into the LSP workflow (e.g., via textDocument/comment).
• Provide a default prompt for generating comments while allowing users to customize it to fit their preferences.

How It Works

1. The user provides raw source code.
2. The LLM analyzes the structure, purpose, and individual lines of the code.
3. The LLM formats and annotates the code with meaningful comments while maintaining the original syntax and structure.
4. A default prompt will be used to ensure consistent, high-quality comments.
5. The user can modify the prompt to adjust formatting, comment style, and level of detail as needed.

Example Use Case

Default Prompt (Can Be Customized by the User):
"Please comment this source code by describing what the function does first. Then line by line describe what it is doing. Put each comment right after the line it is commenting. Improve the formatting when it makes sense to break up lines but don’t add too much vertical space. Return only a text block that will replace exactly the block I just gave you."

User’s Raw Code:

(= (factorial $n)
    (if (= $n 0)
        1
        (* $n (factorial (- $n 1)))))

Generated Output:

; This function calculates the factorial of a given number n.
; The factorial of a number n is defined as:
;    factorial(n) = n * factorial(n-1), with factorial(0) = 1.
; It uses recursion to compute the factorial.

(= (factorial $n)         ; Defines a function 'factorial' that takes one argument n.
    (if (= $n 0)           ; Checks if n is equal to 0.
        1                  ; If n is 0, return 1 (base case).
        (* $n              ; Otherwise, multiply n by:
           (factorial      ; The result of calling 'factorial' recursively on (n - 1).
               (- $n 1))))) ; Decreases n by 1 to progress toward the base case.

Feature Scope & Customization

By allowing them to customize the prompt they should be able to:

• Adjust the level of detail in the comments.
• Control formatting preferences (e.g., spacing, indentation).
• Customize the prompt to suit different coding styles or documentation standards.
• Go back to our default prompt

Error Handling & Fallbacks

• Handle LLM failures, API timeouts, and empty responses gracefully.
• Ensure the original code remains intact in case of errors.
• Provide fallback messages if comments cannot be generated.