Documenting MeTTa Functions - trueagi-io/metta-wam GitHub Wiki

Purpose and Use of @doc

The @doc system in MeTTa is a structured way to document functions and atoms within the language. It allows for clear and consistent documentation directly within the code, making it accessible to both developers and automated tools.

• Purpose:

  • The @doc system is designed to provide detailed descriptions of functions and atoms, including their parameters and return values. This is essential for understanding how different parts of the codebase work and ensuring that the documentation is always up-to-date with the code itself.

• Use:

  • The @doc expressions allow the MeTTa interpreter to automatically extract and display documentation. For example, the get-doc function retrieves the documentation for a given function or atom and presents it in a standardized format (@doc-formal). This makes it easy for users to query and understand the behavior and requirements of different code components.

Example: foldl-atom Documentation

Here is an example of how the @doc system can be used to document the foldl-atom function:

(: foldl-atom (-> Expression Atom Variable Variable Atom Atom))

(@doc foldl-atom
  (@desc "Function takes a list of values, an initial value, and an operation. It applies the operation sequentially to the list of values, using the initial value as the starting point.")
  (@params (
    (@param (@type Expression) (@desc "List of values to iterate over"))
    (@param (@type Atom) (@desc "Initial value for the fold operation"))
    (@param (@type Variable) (@desc "Variable representing the current value in the list"))
    (@param (@type Variable) (@desc "Variable representing the accumulated value"))
    (@param (@type Atom) (@desc "Operation to be applied to the current and accumulated values"))))
  (@return (@type Atom) (@desc "The final accumulated value after applying the operation to all elements of the list")))

Breaking Down the @doc Syntax

1. Function Name:

   • The @doc expression begins with the function name, foldl-atom, indicating the function that is being documented.

2. Description (@desc):

   • The @desc expression provides a plain-text description of the function’s purpose:

     (@desc "Function takes a list of values, an initial value, and an operation. It applies the operation sequentially to the list of values, using the initial value as the starting point.")
     

   • This description explains what the foldl-atom function does in general terms.

3. Parameters (@params):

   • The @params expression lists each parameter of the function, with each parameter described using an @param expression:

     (@params (
       (@param (@type Expression) (@desc "List of values to iterate over"))
       (@param (@type Atom) (@desc "Initial value for the fold operation"))
       (@param (@type Variable) (@desc "Variable representing the current value in the list"))
       (@param (@type Variable) (@desc "Variable representing the accumulated value"))
       (@param (@type Atom) (@desc "Operation to be applied to the current and accumulated values"))))
     

   • Components of @param:
     • @type: Specifies the type of the parameter (e.g., Expression, Atom, Variable).
     • @desc: Provides a brief explanation of what the parameter represents.
   • Example for a single parameter:

     (@param (@type Expression) (@desc "List of values to iterate over"))
     

     This specifies that the first parameter is of type Expression and represents the "List of values to iterate over."

4. Return Value (@return):

   • The @return expression describes what the function returns:

     (@return (@type Atom) (@desc "The final accumulated value after applying the operation to all elements of the list")))
     

   • Components of @return:
     • @type: Indicates the type of the return value (in this case, Atom).
     • @desc: Provides a description of what the return value represents.

This example showcases how the @doc system is used to create comprehensive and structured documentation for functions in MeTTa, ensuring that all relevant information is clearly and consistently presented.

The @doc syntax in MeTTa is fundamentally built on S-Expressions, just like the rest of the language. This consistency means that the documentation is not only human-readable but also easily accessible and manipulable by the interpreter and other tools within the MeTTa ecosystem. Thus, our (parse ...) function can already read it.

Key Points about @doc Syntax:

• S-Expression Format: The @doc system is structured as nested S-Expressions. This format aligns perfectly with the rest of the MeTTa language, making it intuitive for those familiar with S-Expressions.

• Integrated with the Language: Because @doc expressions are S-Expressions, they are fully integrated with the language. This means that the documentation is directly accessible by functions like get-doc, which can retrieve and manipulate these S-Expressions as needed.

• Uniformity: By using the same S-Expression syntax across the language, MeTTa ensures that everything from code to documentation follows the same structural rules. This uniformity simplifies the process of writing, reading, and processing documentation within the language.

• Accessible and Queryable: Since the documentation is in the form of S-Expressions, it can be queried, transformed, or even generated programmatically, making it a powerful tool for both users and developers to interact with the codebase.

In essence, the @doc system's reliance on S-Expressions means that it seamlessly fits into the MeTTa environment, allowing documentation to be as dynamic and accessible as any other part of the code.