MirandaDoc Helper
MirandaDoc Helper is a Visual Studio Code extension that generates Markdown documentation from structured comments in Miranda source files.
The extension is intentionally lightweight: it does not compile Miranda code or implement a full language server. It reads the active .m or .miranda file, finds documentation comments written with ||, associates each block with the next function definition, and generates a Markdown document.
Features
- Registers Miranda files with the
.m and .miranda extensions.
- Provides basic Miranda syntax highlighting.
- Adds snippets for documentation blocks.
- Generates Markdown documentation from the active editor.
- Supports
@param, @returns, @return, and @example tags.
- Groups consecutive pattern-matching equations for the same function in the generated source section.
Write a documentation block immediately before a Miranda function:
|| | factorial
|| Calculates the factorial of a non-negative integer.
|| @param n Non-negative integer.
|| @returns Factorial of n.
|| @example
|| factorial 5
|| => 120
factorial 0 = 1
factorial n = n * factorial (n - 1)
The optional || | name line sets the documentation title. If it is omitted, the extension uses the function name detected from the next definition.
Command
Open a .m or .miranda file and run:
MirandaDoc: Generate Documentation
For saved files, the extension writes a sibling Markdown file named:
<source-file-name>.mirandadoc.md
For untitled files, it opens the generated Markdown in a new unsaved editor.
Snippets
| Prefix |
Description |
mirdoc |
Inserts a documentation block and a function skeleton. |
mirdocblock |
Inserts only the documentation block. |
mirexample |
Inserts an @example section inside a documentation block. |
Example output
# Miranda Documentation
## Contents
- [factorial](#factorial)
## factorial
Calculates the factorial of a non-negative integer.
### Parameters
| Name | Description |
| --- | --- |
| `n` | Non-negative integer. |
### Returns
Factorial of n.
### Example
```miranda
factorial 5
=> 120
```
### Source
```miranda
factorial 0 = 1
factorial n = n * factorial (n - 1)
```
Development
Install dependencies:
npm install
Compile:
npm run compile
Run tests:
npm test
Try the extension locally:
- Open this repository in VS Code.
- Press
F5.
- In the Extension Development Host window, open a
.m or .miranda file.
- Run
MirandaDoc: Generate Documentation.
Scope and limitations
This project is a documentation helper inspired by tools such as JSDoc, JavaDoc, and Haddock, adapted to a small Miranda-focused VS Code extension.
Current limitations:
- It uses a text-based parser, not a complete Miranda parser.
- It only documents functions that have a
|| block immediately above them.
- It does not infer types or validate semantic correctness.
- It does not execute the Miranda interpreter.
Validation checklist
Suggested manual validation for a reviewer:
- Open a
.m file with MirandaDoc comments.
- Run
MirandaDoc: Generate Documentation.
- Confirm that a
.mirandadoc.md file is created.
- Confirm that
@param, @returns, and @example appear correctly.
- Try the
mirdoc, mirdocblock, and mirexample snippets.
- Report the result in a GitHub issue with examples tested and any conflicts found.
