SE

main page

getting started

languages

dex

editors

publications

faq


SE

SE-Lab

RWTH Aachen

Fachgruppe Informatik

How-To: MontiArc Component Documentation


back to MontiArc overview

MontiArc offers a HTML documentation generator similar to JavaDoc. This how-to explains how to enable documentation generation and document components. It is structured as follows:

Enabling Documentation Generator

To enable the MontiArc documentation generator, simply add the goal "doc" to the execution of the montiarc-maven-plugin. HTML documentation is per default generated into folder 'target/madoc'. The following configuration parameters are available to adjust the default behavior of the documentation generator:
  • javaDocUrls: adds further JavaDoc URLS for link resolving. Defaults to 'http://docs.oracle.com/javase/6/docs/api/'.
  • isPublic: set to false, if documentation for subcomponents should be included. Defaults to true.
  • modelDirectory: the directory containing MontiArc models. Defaults to src/main/models.
  • docOutputDirectory: the directory for generated documentation. Defaults to target/madoc.
The simplest configuration that uses the documentation generator is shown in the following listing:

<build>
  <!-- ... -->
  <plugins>
    <!-- ... -->
    <plugin>
      <groupId>de.monticore.lang.montiarc</groupId>
      <artifactId>montiarc-maven-plugin</artifactId>
      <executions>
        <execution>
          <goals>
            <goal>clean</goal>
            <goal>configure</goal>
            <goal>generate</goal>
            <goal>doc</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>


Document Components

MontiArc supports comments in Java style. Hence, a comment that should be included in the documentation starts with /** and ends with */. Comments are always assigned to the next model element. We differentiate between inline and normal tags. Inline tags are enclosed by curly brackets and may be used within the regular documentation text. Normal tags have to be used at the beginning of a comment line. The following tags are supported by the generator:
  • @author[s] 'a' [, 'b']*: single author or a list of authors. Adds an authors segment.
  • @brief 'text': creates an introductory text for the model element.
  • {@code 'text'}: formats 'text' in a typewriter font.
  • @date: adds the current date to the date-segment.
  • @date 'D': adds the date D to the date-segment. D might have the format DD.MM.YYYY or YYYY-MM-DD.
  • {@escape 'text'}: the given 'text' is not interpreted, e.g. tags are not processed and HTML is escaped.
  • @hint 'text': adds a hint-segment that contains the given text.
  • {@link 'name'}: creates a link to the documentation of the model element called 'name'.
  • {@link 'Qualified Typename'}: creates a link to the documentation of the type.
  • {@link 'Qualified Typename#methodname'}: creates a link to the documentation of the method.
  • {@link 'Qualified Typename#methodname(t1, t2, ?)'}: creates a link to the documentation of the method with parameter types t1, t2, and undefined.
  • @param 'pName' 'single-line text': adds 'single-line text' as documentation of component configuration parameter 'pName' into the parameters-segment.
  • {@param 'pName' 'multi-line text'}: adds 'multi-line text' as documentation of component configuration parameter 'pName' into the parameters (since 2.4.0).
  • @rev 'text': adds 'text' to the revision-segment.
  • @see 'Typename': adds a see-segment with a link to the documentation of the given type.
  • @sideEffects 'text': adds a side-effects warning box to the top of the documentation that contains the given text. Text is a single-line comment.
  • {@sideEffects 'text'}: adds a side-effects warning box to the top of the documentation that contains the given text. Text is a multi-line comment.
  • @since 'text': adds a since-segment that contains the given text (since 2.4.0).
  • @state 'text': adds a state warning box to the top of the documentation that contains the given text. Text is a single-line comment (since 2.2.0).
  • {@state 'text'}: adds a state warning box to the top of the documentation that contains the given text. Text is a multi-line comment (since 2.2.0).
  • @stateless: adds an info to the state-segment, that this component is stateless. (since 2.2.0)
  • @type 'gtName' 'text': adds 'text' as documentation of generic type parameter 'gtName' into the generic types-segment.
  • @version 'text': adds 'text' to the versions-segment.
A simple example demonstrating the effects of the listed tags is depicted in the following figure:

Tags and Effects: Click to enlarge

Index Page Design

In order to influence the design of the index page of a generated documentation, the following steps have to be taken:
  • Create a file named 'documentation_main.html' in the root model folder (e.g. src/main/models).
  • The following tags are supported within this document:
    • @title 'text': sets the titel of the whole documentation.
    • @brief 'text': short title of the documentation.
    • @version 'text': version of the documentation.
  • Use regular HTML to design the index page, e.g. add images or links to websites.

Package Documentation

Similar to Java it is possible to generate a documentation for packages. For this purpose, a file named 'package.html' has to be created in the according package. The text contained is shown in the package overview of the generated documentation.

Back to top.