# Documentation and I18N

# Documenting Components

Igor provides an online help for every component that is documented. The help is opened by clicking the help button button in the parameter editor.

Component documentation must be in Markdown format and placed in the following directory in the classpath:

doc/

The file containing a component's documentation must be name like the component's type ID, e.g.

doc/custom-component.md

where custom-component ist the component's type ID.

I18N of component documentation is supported by placing translated documentation files in subdirectories that are named like the respective locale.

E.g. a translated documentation in german for the custom component must be placed in a classpath directory like:

doc/de_DE/custom-component.md

If no translated documentation for the current user's locale is found, igor will fall back to the standard documentation (if it exists).

# I18N

Igor supports translation of categories, types and parameters of components. In order to use the translation you have to place properties files in the following directory in the classpath:

i18n/

E.g. the translation for your custom components could be placed in the file:

i18n/custom-labels.properties

Translations must be placed in subdirectories that are named like the respective locale.

E.g. a german translation for your custom components must be placed in:

i18n/de_DE/custom-labels.properties

All properties files from the classpath residing in an i18n/ directory will be used as message source for translations.

# I18N Example

For a custom component...

/**
 * A custom action.
 */
@IgorComponent(categoryId = "custom-actions-category", typeId = "custom-action-type")
public class CustomAction extends BaseAction {

    /**
     * A sample parameter.
     */
    @IgorParam
    private boolean addMessage = true;

    ...
}

...the properties file might look like this:

# Category-ID label
custom-actions-category=Custom Actions

# Type-ID label
custom-action-type=Special Action

# Igor parameters of components:
custom-action-type.addMessage=Really add message?

The labels defined will be used in igor's UI and in generated component documentation.

# Generating Documentation

Since keeping code and documentation in sync is difficult, you can use the igor-maven-plugin to generate documentation of your custom components.

Java 17 Features

Igor uses JavaParser (opens new window) to parse component source files and generate documentation from them.

The parser supports Java only up to language level 15 at the moment. Since igor requires Java 17, you might use langueage features in components that lead to parser errors during documentation generation, e.g.:

[ERROR] Could not parse file AddDataAction.java (generated documentation 
might be incomplete): (line 112,col 21) Use of patterns with instanceof is not 
supported.

In these cases you should provide manual documentation for the respective component as described above.

In order to use the plugin you have to enable it your project's pom.xml file:

<plugin>
    <groupId>com.arassec.igor</groupId>
    <artifactId>igor-maven-plugin</artifactId>
    <version>0.6.6</version>
    <executions>
        <execution>
            <goals>
                <goal>DocGen</goal>
            </goals>
        </execution>
    </executions>
</plugin>

The plugin will scan all igor components under src/main/java and generate component documentation from the component's JavaDoc comments in the directory:

src/main/resources/doc-gen

The precedence to determine which documentation file to use, if multiple for the same type ID exist, is:

  • First try manually created documentation for the user's current locale, e.g. doc/de_DE/custom-component-type.md
  • If that doesn't exist try default, manually created documentation under doc/, e.g. doc/custom-component-type.md
  • If there is still no documentation found, try generated documentation under doc-gen, e.g. doc-gen/custom-component-type.md

The following HTML elements are converted to their Markdown equivalents during generation:

HTML Element Generation Result
<h2>heading2</h2> ... <h6>heading6</h6> # heading2 ... ###### heading6
<br> \n\n
<strong>text</strong> **text**
<b>text</b> **text**
<i>text<i> *text*
<a href="https://www.arassec.com">arassec</a> [arassec](https://www.arassec.com)
HTML tables Markdown tables
<pre>text</pre> `text`
<pre><code>text</code></pre> \n```text```\n
<p>text</p> \n\ntext\n
<ul><li>first</li><li>second</li></ul> * first\n* second\n\n

Due to changes in JavaDoc-Linting HTML <h1> headings are not supported anymore!

# Code-Gen Example

E.g. for the following component...

/**
 * <h1>Custom Action</h1>
 * An action providing <strong>really</strong> usefull functionality.
 */
@IgorComponent(categoryId = "custom-actions-category", typeId = "custom-action-type")
public class CustomAction extends BaseAction {

    /**
     * A sample parameter. For details see <a href="https://intra.net">here</a>.
     */
    @IgorParam
    private boolean addMessage = true;

    ...
}

... the following documentation would be generated:

# Custom Action

An action providing **really** usefull functionality.

## Parameters
The component can be configured by the following parameters:

Parameter | Description
:---|:---
addMessage | A sample parameter. For details see [here](https://intra.net)