Skip to main content

API documentation

rascal-0.42.0

Synopsis​

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

Documentation tags attach an inline concept description to any Rascal declaration. Inside the tag you can use an entire structure of a tutor concept.

info

Previously there was a single @doc tag with all the sections of a concept internally. Now we use different tags for each concept. The old notation is deprecated but still supported for backward compatibility.

These tags will be used by the tutor compiler to document any Rascal declaration:

  • @synopsis
  • @description
  • @examples
  • @benefits
  • @pitfalls

The @synopsis tag is not optional. The others are optional.

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.42.0</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 Code Examples 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.