Child pages
  • Documentation comments

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 4.0

Documentational comments in code help understannding the implemented functionality. In this short tutorial we will learn how to add support for such comments into your languages. You may like to first check out our Commenting out cookbook, where we show how to allow for commenting pieces of code out. In MPS these two typical use-cases for comments in code are better kept separate on the implementation level. This cookbook continues from where we left in the Commenting out cookbook.

The Calculator language

We chose the Calculator tutorial language as a testbed for our experiments. You can find the calculator-tutorial project included in the set of sample projects that comes with the MPS distribution. We will allow both the input fields and the output fields to hold additional documentational comments I recommend you skimmed through the tutorial to familiarize yourself with the language before we continue.

Outline

In order to enable comments, we'll go through a few simple steps:

  • We need to be able to indicate which elements can hold documentary comments. It will be both InputFields and OutputFields in our case
  • We create an annotation that can be attributes to commentable nodes and carries the text of the comment
  • We provide a pair of intention actions to add/remove comment to/from a node

Enhancing the fields

First we need a marker interface to indicate which nodes may hold additional documentational comments.


Both InputField and OutputField need to implement the interface:

An annotation for comments

Now we should add a new annotation that can be attributed to nodes implementing ICanHaveComment. For our simple case we'll use a single string property to hold the comment.

MPS now complains about missing information about the annotation - which nodes can it annotate and what role will it have. Alt + Enter will help us invoke a quick-fix that will add the required information to the annotation concept:
Now we need to specify the role as well as the attributed nodes by filling out the particular properties:


The annotation will be attributed to ICanHaveComment concepts only and will take the comment role.

Editor

The editor of the annotation will place the comment right above the attributed node and prepend it with //.

Intentions

We'll use Intentions to add and remove comments to/from nodes. So we create a new intention for ICanHaveComment, allow it for nodes without a comment and implement the execute() method:

We may need to import the actions language (Control + L):

Similarly we need an intention for removing comments:

Setting focus

When adding comments, it would be useful if the intention left the caret positioned within the comment text so that the user can immediately start typing the comment text. Using the selection methods of EditorContext will do the trick:

You may need to add the MPS.Editor module to the dependencies of your language to enable the selection methods:

Using comments

After recompilation we will be able to add comments to input and output fields.

Summary

We learned how to enable documentational comments for custom languages using annotations. Since the text of the comment as well as the rules for its presentation are separate from the node the comment is attributed to, this mechanism can be used to enable comments in both existing and new languages.