Name Tutor/Markup/SourceCodeMarkup/DocAnnotations

Synopsis A doc annotation attaches an inline concept description to a Rascal declaration.

Description All Rascal declarations can be preceeded by an annotation of the form @doc{ ... } where ... may be arbitrary text, provided that { and } characters are balanced and that unbalanced braces are escaped like \{ or \}. This text is expanded to a full concept definition when the concept is needed for editing or regeneration of a course.

The Tutor supports and expands inline concept descriptions for the following declarations types.

Module Declaration

1. The name of this module is collected.
2. The header of the concept definition is automatically generated. It is surrounded by the markers <AUTOINSERTED> ... </AUTOINSERTED> and consists of:
   • Name: followed by the module name.
   • Usage: followed by an appropriate import declaration.

Note that this expansion is only needed to generate a full concept definition; it will not occur in the source text.

Function Declaration

1. The signatures of this function and of all directly following functions with the same name are collected. The signatures are placed in an itemized list (unless there is only one).
2. The header of the concept definition is automatically generated. It is surrounded by the markers <AUTOINSERTED> ... </AUTOINSERTED> and consists of:
   • Name: followed by the function name.
   • Function: followed by the function signature(s).
   • Usage: followed by an appropriate import declaration.

Data Declaration

1. The signatures of this data declaration and of all directly following data declarations without their own @doc annotation are collected.
2. The header of the concept definition is automatically generated. It is surrounded by the markers <AUTOINSERTED> ... </AUTOINSERTED> and consists of:
   • Name: followed by the name of the first data declaration.
   • Type: followed by the data declaration(s).
   • Usage: followed by an appropriate import declaration.

Annotation Declaration

1. The signature of this annotation declaration is collected.
2. The header of the concept definition is automatically generated. It is surrounded by the markers <AUTOINSERTED> ... </AUTOINSERTED> and consists of:
   • Name: followed by the name of the annotation declaration.
   • Type: followed by the annotation declaration.
   • Usage: followed by an appropriate import declaration.

Examples We only give an example of documenting a simple function. Read the source code of Rascal library files for other ones.

Consider the source code of the now function in the Rascal:DateTime library.

  @doc{
  Synopsis: Get the current datetime.

  Examples:
  <screen>
  import DateTime;
  now();
  </screen>
  }
  @javaClass{org.rascalmpl.library.DateTime}
  public java datetime now();

This will be expanded to

  <AUTOINSERTED>
  Name: now
  Function: 
  `datetime now()`
  Usage: `import DateTime;`
  </AUTOINSERTED>

  Synopsis: Get the current datetime.

  Examples:
  <screen>
  import DateTime;
  now();
  </screen>

and the final result is Rascal:now.

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.
• Inline concepts are designed to fully allow the mixed editing and modification of an inline concept in an (Eclipse or other) source code editor and in the Tutor's own concept editor. When saving a modified inline concept in the Tutor editor, the corresponding Rascal source code file is immediately updated.

Pitfalls This approach requires that functions with the same name are grouped together in the source file.

[Edit] | [New Subconcept] | [Recompile Course] | [Warnings]