Comments and annotations

A chart is read far more often than it is written, and much of the reading happens in the diagram. This chapter is about the parts of a .sctx file that are there for the reader: comments, some of which KIELER draws in the diagram; labels, which replace code in the diagram with words; annotations, which steer the layout (and occasionally the compiler); and pragmas, which apply to the whole file. Along the way it covers two comment traps that can quietly change what a chart does.

Ordinary comments

// starts a comment that runs to the end of the line, and /* ... */ encloses a comment that can span lines. Both are ignored by the compiler and by the diagram. In SCCharts Lab, a // comment on the line above a declaration also shows up when you hover over the declared name.

Doc comments in the diagram

A comment that starts with /** is a doc comment. It belongs to the element written right after it: the chart, a declaration, a state, a region, a transition, an action or an equation. KIELER draws the doc comments of the chart, its states and its regions as yellow comment boxes attached to their element, and the doc comment of a transition as an extra label on its arrow:

LampChart

Open in the playground

Diagram

Code

/** Switches the lamp on and off with one button. */
scchart Lamp {
  /** The push button, true while pressed. */
  input bool button
  output bool light = false

  /** Waiting for a press. */
  initial state Off
  /** Press: switch on. */
    if button do light = true go to On

  /** The lamp is lit. */
  state On
    if button do light = false go to Off
}

The doc comments of the chart and of both states as comment boxes, and the transition’s comment, “Press: switch on.”, as an extra label on its arrow.

Comment boxes are an option of the diagram, “Comment Nodes”, which is on by default. The annotation @diagram[commentNodes] false before scchart turns it off for one chart (more on annotations below). Doc comments change nothing in the behaviour.

A doc comment must stand where an element can follow. Inside a transition (if button /** x */ go to On) it is a syntax error, no viable alternative at input '/** x */', and so is a doc comment after the last state of a region, with nothing left for it to describe.

There is also a one-line form for declarations, the declaration comment: //* at the end of a declaration attaches the rest of the line to it.

input bool button          //* the push button, true while pressed
output bool light = false  //* the lamp

SCCharts Lab shows these in its hover card for the declared name. The form is allowed only at the end of a declaration: at the end of a transition line, say, it is a syntax error (no viable alternative at input '//* switch on\n').

Two comment traps

Both traps come from the same detail of KIELER’s grammar: a // comment must be followed by at least one character that is not *, and the line break itself counts as that character.

An empty // swallows the next line

SwallowedSimulation

Open in the playground

Diagram

Code

scchart Swallowed {
  input bool button
  output bool light = false

  initial state Off //
    if button do light = true go to On

  state On
    if button do light = false go to Off
}

Step

Tick 0 of 3

Inputs for tick 1

button Boolean input: true while on. It keeps its value until you change it.

Timing diagram of Swallowed

Tick	input bool button	output bool light	Active state of the chart

Click a tick to show it, or use the Left and Right arrow keys to go back and step.

Guided tour, 3 ticks Press Next to run tick 1, or Take over to set the inputs yourself.

Previous Next Take over

Guided tour, 3 ticks:

1. button = falseTick 1 enters Off. KIELER warns that On is not reachable, which is the only hint that something is wrong.
2. button = trueThe button is pressed, but light stays false: the line if button do light = true go to On was swallowed by the empty // above it, so Off has no outgoing transition.
3. button = falseNothing will ever happen in this chart.

1 warning and 1 note

• Note, line 6, column 1KIELER treats this line as part of the empty // comment on the line aboveAn empty // comment at the end of a line also comments out the whole next line in KIELER. Write something after the //, or delete it.
• Warning, line 8, column 3State On can never be enteredKIELER says: The state is not reachable.No transition leads to it from a reachable state, and it is not initial. Add a transition to it, or delete it.About this message

Press the button: the light never comes on. The transition below the empty // is not part of the chart.

initial state Off // ends with an empty comment. KIELER’s comment rule takes the line break after // as the comment’s first character and then continues to the end of the next line. So the whole line if button do light = true go to On becomes part of the comment, Off has no transition, and the only hint is the warning The state is not reachable. on On.

A chart that silently loses a line

This happens in files with Unix line endings (LF), which is what most editors on Linux and macOS write and what many projects use everywhere. In a file with Windows line endings (CRLF) the \r is the comment’s character and nothing is lost, so the same chart can behave differently on two machines. Never end a line with a bare //; give the comment some text, or delete it.

A //* banner is not a comment

Many C programmers frame headings with lines of asterisks. In SCTX a line starting with //* is the declaration comment from above, and before the chart there is nothing for it to belong to:

LampBannerChart

Open in the playground

Diagram

Code

//**********************************
// Lamp controller
//**********************************
scchart LampBanner {
  input bool button
  output bool light = false

  initial state Off
    if button do light = true go to On

  state On
    if button do light = false go to Off
}

KIELER rejects this chart

• Line 1, column 1Expected an scchart but found a //* commentKIELER says: missing EOF at '//**********************************\n'A file contains imports, pragmas and charts written as scchart Name { ... }.About this message

The banner above scchart makes the whole file unreadable for KIELER. (This site still draws the chart, so that you can see what was meant.)

KIELER stops at the first line with missing EOF at '//**********************************\n'. That is all official KIELER says; SCCharts Lab adds

There is no SCChart to compile. Add a scchart declaration first.

Inside a chart, a banner line that follows a declaration does not fail: it silently becomes that declaration’s comment. Put a space after the slashes (// ****) or use /* ... */ for banners.

One relative of these traps: /**/, an empty block comment, is read as the start of a doc comment (/**) that only ends at the next */ in the file.

Labels

A diagram is easiest to read when it says what a transition means rather than how it is computed. Labels replace the name of a state or region, or the trigger and effects of a transition or action, with your own words:

KettleChart

Open in the playground

Diagram

Code

scchart Kettle "Kettle controller" {
  input bool lever, boiling
  output bool heater = false

  initial state Idle "Waiting"
    if lever do heater = true go to Heating label "lever down"

  state Heating {
    exit do heater = false label "heater off"
  }
  if boiling go to Idle label "water boils"
  if !lever go to Idle label "lever up"
}

The diagram shows “lever down” and “water boils” instead of the triggers and effects; switch to Code to see what they hide.

Element	Syntax
chart	scchart Kettle "Kettle controller" { ... }
state	state Idle "Waiting"
region	region Lamp "The lamp" { ... }
transition	if lever do heater = true go to Heating label "lever down"
entry, during or exit action	exit do heater = false label "heater off"

A label of a state or region is shown in place of its name; the name is still what transitions and references use. A label of a transition or action is shown in place of its trigger and effects, and KIELER reminds you of that with the notes The trigger of this action is hidden by the label. and The effects of this action are hidden by the label. In KIELER the “User Labels” option of the diagram turns the labels off again. Labels never change behaviour.

Annotations

An annotation is a name starting with @, written before the element it applies to. It comes in three shapes:

// a tag:
@HVLayout
// a name with a value:
@DefaultSleep 50
// a name with a key and a value:
@layout[elk.direction] DOWN

Most annotations only affect the diagram:

Annotation	Where	Effect
@layout[elk.direction] DOWN	chart, state, region	lays out that level DOWN, UP, LEFT or RIGHT
@HVLayout, @VHLayout	chart, state, region	the order in which the levels alternate between horizontal and vertical layout (the default is @HVLayout)
@hide	state, region, transition, declaration	leaves the element out of the diagram, along with transitions from or to a hidden state
@collapse, @expand	region	draws the region collapsed, or expanded
@diagram[userLabels] false	chart	sets one of the diagram’s options for this chart, here “User Labels”
@foreground, @background	state	colours (this site’s diagrams ignore them, so that they suit both themes)

Hidden is not switched off. In this chart the region that counts presses carries @hide:

LayoutSimulation

Open in the playground

Diagram

Code

scchart Layout {
  input bool button
  output bool light = false
  output int presses = 0

  @layout[elk.direction] DOWN
  region Lamp {
    initial state Off
      if button do light = true go to On

    state On
      if button do light = false go to Off
  }

  @hide
  region Counter {
    initial state Count
      if button do presses++ go to Count
  }
}

Step

Tick 0 of 4

Inputs for tick 1

button Boolean input: true while on. It keeps its value until you change it.

Timing diagram of Layout

Tick	input bool button	output bool light	output int presses	Active state of region Lamp	Active state of region Counter

Click a tick to show it, or use the Left and Right arrow keys to go back and step.

Guided tour, 4 ticks Press Next to run tick 1, or Take over to set the inputs yourself.

Previous Next Take over

Guided tour, 4 ticks:

1. button = falseAnnotations change the diagram, not the behaviour. Tick 1 enters Off and, in the hidden region, Count.
2. button = truelight = true, and presses = 1: the region you cannot see still runs.
3. button = falseNothing fires.
4. button = truelight = false, presses = 2.

The counter region is not drawn, but presses goes up with every press.

A few annotations change what the compiler does. They appear in the chapters about their features: @HardReset, @SimulateSleep, @DefaultSleep, @IntegerClockType and @NoSleep in Time, and @C / @Java on extern names in Host code.

A misspelt annotation does nothing, silently

KIELER accepts any annotation name and ignores the ones it does not know. Write @HardRest instead of @HardReset and the period quietly keeps its default soft reset, with no warning. If an annotation seems to have no effect, check its spelling first.

Pragmas

A pragma is a line starting with # that applies to the whole file. Pragmas and import lines go at the top, in any order, before the first scchart; a pragma after a chart is a syntax error (missing EOF at '#'). The ones you are likely to meet:

Pragma	Purpose	Chapter
#hostcode "...", #hostcode-c "...", #hostcode-c-header "...", #hostcode-java "..."	C or Java text pasted into the generated files	Host code
#resource "file"	copies a file next to the generated code and compiles it with it	Host code
#code.naming "prefix"	renames the generated functions and data struct	From chart to C

The KIELER wiki’s page on annotations and pragmas lists a few more for special set-ups.

Try it

A diagram that explains itself

Document the doorbell: give the chart and both states doc comments, put a //* comment on the input, and label the two transitions “pressed” and “after one tick”. Check your work in the diagram: the comment boxes and the two labels should appear there. Comments and labels never change behaviour, so the playground’s comparison with the model solution matches even before you start; run it at the end to make sure that you did not change anything else.

Open the starter in the playground

Show the starter chart

scchart Doorbell {
  input bool press
  output bool ring = false

  initial state Quiet
    if press do ring = true go to Ringing

  state Ringing
    do ring = false go to Quiet
}

Show a solution

/** Rings for one tick per press. */
scchart Doorbell {
  input bool press  //* the bell push
  output bool ring = false

  /** Waiting for someone at the door. */
  initial state Quiet
    if press do ring = true go to Ringing label "pressed"

  /** The bell is ringing. */
  state Ringing
    do ring = false go to Quiet label "after one tick"
}

Open the solution in the playground

Check your understanding

Which of these lines, at the top of a file before scchart, makes KIELER reject the file?

A// ===== Lamp controller =====B/* ***** Lamp controller ***** */C/** Lamp controller */D//***** Lamp controller *****

Show the answer

Answer D: //***** Lamp controller *****

A line starting with //* is a declaration comment, and there is no declaration before scchart for it to belong to: missing EOF at .... An ordinary // or /* */ comment is ignored, and a /** */ doc comment before scchart belongs to the chart.

A transition has label "door opens". What changes in the simulation?

ANothing: labels only change the diagramBThe transition fires only when the label matches an inputCThe trigger is ignoredDThe effects no longer run

Show the answer

Answer A: Nothing: labels only change the diagram

A label replaces the trigger and effects in the diagram only. KIELER notes that they are hidden, but the transition behaves exactly as before.

Key ideas

• // and /* */ comments are ignored. /** */ doc comments belong to the next element and KIELER draws them in the diagram; //* at the end of a declaration is a one-line doc comment.
• Never end a line with a bare //: in LF files it swallows the next line. Never start a banner with //*.
• Labels (state S "...", label "...") replace names, triggers and effects in the diagram, never the behaviour.
• Annotations (@...) steer the layout and a few compiler features; unknown or misspelt names are ignored without a warning.
• Pragmas (#...) apply to the whole file and go before the first scchart.

Next, Host code: calling C or Java from a chart.