//////////////////////////////////////////////////////////////////////////////
// Copyright (c) 2023, 2026 Contributors to the Eclipse Foundation
//
// See the NOTICE file(s) distributed with this work for additional
// information regarding copyright ownership.
//
// This program and the accompanying materials are made available
// under the terms of the MIT License which is available at
// https://opensource.org/licenses/MIT
//
// SPDX-License-Identifier: MIT
//////////////////////////////////////////////////////////////////////////////

include::../_part_attributes.asciidoc[]

indexterm:[annotation, doc]
indexterm:[doc, annotation]

:leveloffset: -2

[[lang-tut-annotations-documentation]]
== Documentation annotations

Documentation can be added to all elements of the specification that support <<lang-tut-annotations,annotations>>:

[source, cif]
----
@doc("The lower limit sensor of the elevator.")
@doc("Safety sensor.")
input bool ElevatorDownSensor;
----

The documentation may span multiple lines, by using explicit newline characters:

[source,cif]
----
@doc(
    "doc with multiple\n" +
    "lines of\n" +
    "text"
)
input bool i;
----

This also may be abbreviated as follows, by using multiple arguments:

[source,cif]
----
@doc(
    "doc with multiple",
    "lines of",
    "text",
)
input bool i;
----

It is also possible to use for instance constants from the model in the documentation text:

[source,cif]
----
const int MAX_NR_OF_PRODUCTS = 3;

@doc(fmt("Sensor 1/%d.", MAX_NR_OF_PRODUCTS))
input bool s1;
----

This documentation can then be used by CIF tools in various ways.
For instance, if the <<tools-codegen-chapter-index,CIF code generator>> is used to generate Java code for the above example, then the documentation is included in the generated code:

[source, java]
----
/**
 * Input variable "ElevatorDownSensor".
 *
 * <p>
 * The lower limit sensor of the elevator.
 * </p>
 *
 * <p>
 * Safety sensor.
 * </p>
 */
public boolean ElevatorDownSensor;
----

For more detailed information on documentation annotations, see the <<lang-ref-annotations-documentation,reference manual>>.
