Skip to main content

API documentation

rascal-0.34.0
rascal-tutor-0.18.4

Synopsis​

The Tutor compiler reads Rascal source files and produces Concept markdown files for each Rascal module.

Description​

The compiler generates for every Module.rsc a markdown file with the following structure:

---
title: <moduleName>
---
<div class="theme-doc-version-badge badge badge--secondary">rascal-0.34.0</div> <div class="theme-doc-version-badge badge badge--secondary">rascal-tutor-0.18.4</div>


// for each declaration (function, data, syntax, alias, import, extend)
#### Synopsis

...
#### Description
...

// etc.

So, for all standard Concept headers, like Synopsis and Benefits there is a place at every declaration.

The content of the header paragraphs is either directly derived from source code (like function signature and data definitions), or it is taken from the following tag definitions on each declaration:

  • @doc may contain literally the headers of a Concept, like #### Synopsis. This notation is deprecated in favor of the tags below.
  • @synopsis is a single line description of the definition.
  • @description is a multi-line explanantion of the definition.
  • @benefits, @pitfalls, @examples, @types, @name and @function each follow the intent of the standard Concept headers.

The documentation written for features without an explicit synopsis is not rendered. In other words it is obligatory to use at least a @synopsis tag or start with a #### Synopsis header..

Benefits​

  • A (small) part of documentation writing is automated. The information about the name of a function, data or annotation declaration, or its signature is always consistent.
  • You can write examples of the usage of each definition using Listing markup that is run and checked at documentation compile-time.

Pitfalls​

  • This approach requires that functions with the same name are grouped together in the source file.
  • You need to run the tutor compiler before errors in the documentation tags are detected.