Document a command

This chapter demonstrates how to document a command with advanced formatting and functions.

You can use classes, methods or write human tasks with HTML. How to document your command changes based on what approach was chosen.

You can also apply the HTML logic of this guide to the documentation of workflows.

This guide only applies to the documentation visible in the workflow executor.

1. Introduction

In this howto you learn how you can improve your documentation by using selected HTML tags.

Advanced option can also be used in Human Tasks and workflows.

Any advanced option covered by this guide is only applicable to the documentation of the full command, not to its inputs and outputs!

2. Prerequisites

To complete this guide you need:

Roughly 10 minutes
JDK11+ installed with JAVA_HOME configured appropriately
An IDE (we recommend IntelliJ)
Some kind of build tool (like gradle, maven or ant)
Know how to use the Single Command Runner in the Workflow Executor

3. Document your command

For the following examples a java command is used. How to apply these concepts to human tasks will be explained at the end of this guide.

3.1. Using classes as Commands

You can document your command by using the @workflowDocu annotation in the javaDoc like follows:

[...]

/**
 * This is a sample command for displaying purposes
 *
 * (1)
 * @workflowDocu  This is the documentation of this command!
 */
@JavaCommand
public class Example {
	[...]
}

Figure 1. The resulting documentation.

1	The `@workflowDocu` annotation in the javaDoc signalizes that the text afterwards should be regarded as documentation of the command.

The input field can be documented as follows:

[...]
@JavaCommand
public class Example {

    /**
     * @workflowDocu  This is the documentation of the input! (2)
     *
     */
    @Persistent
    private String input;
}

The documentation will be shown here:

Figure 2. Documented input

1	Click on the info icon.
2	Under the documentation headline, the `@workflowDocu` marked text will appear.

3.2. Using methods as commands

When creating commands from legacy code, you might create commands from methods. Their documentation works different from using a class as command. The regular documentation of the command still needs to be marked with @workflowDocu. The documentation of inputs and outputs will be taken from the @param <parameter name> and @return annotation respectively.

[...]

@JavaCommandService
public class ExampleMethodCommandClass {

	/**
	 * @workflowDocu This is regular command documentation! (1)
	 *
	 * @param input This is input documentation! (2)
	 * @return This is output documentation! (3)
	 */
	public String example(final String input) {
		return "Input was: " + input;
	}
}

Figure 3. Command generated from a method

Figure 4. Documentation of an input of a command generated from a method

Figure 5. Documentation of an output of a command generated from a method

1	Regular command Documentation. In this part you can also you the advanced options.
2	Documentation of the parameter is the same as the documentation of the input.
3	Documentation of the return value is the same as the documentation of the command output.

4. Writing advanced documentation

Sometimes plain text might not be enough to explain complex commands. Then you might want to use formatting, styling and maybe some functional tags to empower your documentation. You can do this by using following HTML tags: <p>, <h1>, <h2>, <h3>, <h4>, <h5>, <h6>, <div>, <br>, <b>, <strong>, <table>, <a> and <code>. How these effect you documentation, will be explained in the following paragraphs!

The given examples are using classes as commands. If you are using methods as commands, you can still use these tags in the documentation text!

4.1. Formatting

4.1.1. Linebreak

If you want to format the text with a linebreak, you need to use the HTML tag <br>:

[...]

/**
 * This is a sample command for displaying purposes
 *
 *
 * @workflowDocu  This is the documentation of this command! (1)
 *                This results in the line to be continued! <br> (2)
 *                This will be displayed in the next line!
 */
@JavaCommand
public class Example {
	[...]
}

Figure 6. The resulting documentation.

1	Regular line breaks in the source code will have no effect on the displayed documentation in the workflow executor.
2	The `br` tag will result in a linebreak at its location.

4.1.2. Paragraph

You can also use paragraphs, using the HTML tag <p>:

[...]

/**
 * This is a sample command for displaying purposes
 *
 *
 * @workflowDocu  This is the documentation of this command!
 *                <p> (1)
 *                This is the paragraphs content!
 *                </p> (2)
 *                This will be displayed in the next line!
 */
@JavaCommand
public class Example {
	[...]
}

Figure 7. The resulting documentation.

1	Paragraphs will always leave an empty line to the content before, if there is any!
2	Paragraphs will always space them self one line apart to the content following the paragraph!

The tags <p>, <div>, <table> and heading tags <h1-6> are unavailable whilst within a paragraphs ⇒ No nesting of these tags inside paragraphs!

4.1.3. Headings

The documentation supports 6 different headings. You can use those with the tags <h1>, <h2>, <h3>, <h4>, <h5> and <h6> with the biggest heading being <h1> and the smallest being <h6>.

Headings can be used in the same way as paragraphs, but they affect font size and text style. Common usage is for dividing the documentation into smaller sections.

4.1.4. Container

Containers work differently as how they would work in a regular HTML file!

Containers in the documentation mark a new line before and after the content.

[...]

/**
 * This is a sample command for displaying purposes
 *
 *
 * @workflowDocu  This is the documentation of this command!
 *                <div> (1)
 *                This is the containers content!
 *                </div> (2)
 *                This will be displayed in the next line!
 */
@JavaCommand
public class Example {
	[...]
}

Figure 8. The resulting documentation.

1	Containers always start in a new line!
2	Any content after the container will start in a new line!

Containers can be used for wrapping multiple tags.

An example of that is:

[...]

/**
 * This is a sample command for displaying purposes
 *
 *
 * @workflowDocu  This is the documentation of this command!
 *                <div> (1)
 *                <p>
 *                This is the first paragraph!
 *                </p>
 *                <p>
 *                This is the second paragraph!
 *                </p>
 *                <p>
 *                This is the third paragraph!
 *                </p>
 *                </div> (2)
 *                This will be displayed in the next line!
 */
@JavaCommand
public class Example {
	[...]
}

Example 1. Command run with no optional inputs

1	The container starts in a new line before the paragraph lists adds it own spacing.
2	The paragraph adds its spacing before the container ends by entering a new line.

With longer lists it gets easier to spot where the list starts and ends using the <div> tag.

4.1.5. Table

You can use tables in your documentation.

Tables have a fixed format. You cannot change it!

A table only supports plain text. It ignores any tags that are not part of the table.

This is how a table can be structured:

[...]

/**
* This is a sample command for displaying purposes
*
*
* @workflowDocu  This is the documentation of this command!
*                <table> (1)
*                <tr> (2)
*                <th> (3)
*                Table Heading of column one
*                </th> (3)
*                <th>
*                Table Heading of column one
*                </th>
*                </tr> (2)
*                <tr>
*                <td> (4)
*                Some table content
*                </td> (4)
*                <td>
*                Some more table content
*                </td>
*                </tr>
*                <caption>This is an example table!</caption> (5)
*                </table> (1)
*                This will be displayed in the next line!
*/
@JavaCommand
public class Example {
[...]
}

Figure 9. The resulting documentation.

1	Everything within the `<table>` tag is parsed as part of the table. Unknown or wrongly placed tags or elements will be ignored.
2	A table row is signified with the `<tr>` tag. A table row can contain multiple elements that are the contents of this row.
3	A table head `<th>` is a special kind of table content as they can be seen as a headline.
4	Regular table data is marked with the `<td>` tag.
5	(Optional) This is a `<caption>` for the table that will be displayed above the Table.

You can space the table from the surrounding documentation by nesting the table into containers!

4.2. Styling tags

Inline styles will be ignored.

4.2.1. Making text bold

There are currently two different options of making certain text elements bold: Using <b> or <strong>

Both tags work in the exact same way! The only difference between the two is a semantic difference: Use <strong> to highlight something and use <b> out of a stylistic choice!

[...]

/**
 * This is a sample command for displaying purposes
 *
 *
 * @workflowDocu  This is the <strong>documentation</strong> of this command! (1)
 *                I still want this <b>bold!</b> (2)
 */
@JavaCommand
public class Example {
	[...]
}

Figure 10. The resulting documentation.

1	Making `documentation` bold out of an emphasis on this part!
2	Making `bold!` bold out of a stylistic choice!

4.3. Functional tags

Only plain text is allowed within those tags!

4.3.1. Links

You can embed links into your documentation with the <a> tag:

[...]

/**
 * This is a sample command for displaying purposes
 *
 *
 * @workflowDocu  More information available on our <a href='https://pak.asap.de/'>website</a>! (1)
 */
@JavaCommand
public class Example {
	[...]
}

Figure 11. The resulting documentation.

1	The word `website` will have an on click event, which opens an external website in your default browser. The URL specified behind the `href` is the website that opens, in this case `https://pak.asap.de/`!

4.3.2. Examples

If you want to add an example that the user can copy, you should use the <code> tag. The user then can click on the text to copy it into the clipboard

This also has a style to highlight the example!

[...]

/**
 * This is a sample command for displaying purposes
 *
 *
 * @workflowDocu  Try to run the command with following input:<code>This is an example that can be used to run the command</code> (1)
 */
@JavaCommand
public class Example {
	[...]
}

Figure 12. The resulting documentation.

1	The example being highlighted and having an on click event pasting the content into the clipboard for pasting into command inputs!

5. Human Task Documentation

You can use all the different option listed above in human tasks.

Documenting human tasks is fundamentally different from documenting java commands.

5.1. Documenting a human task

In a human task is a container, that is of class meta. This class contains the meta information about the human task. In this container we also document the human task.

Using the advanced formatting options is not as simple as in java. The tags will regularly be interpreted as part of the actual file and not as part of the documentation text. For that reason you need to escape the HTML tags in your documentation.

The meta information can look like this:

<div class="meta"><!-- Meta info for human task interpreter -->
<#command major="1" minor="0" increment="0" group="HumanTasks.Generic"
workflowDocu="A link to our &lt;a href='https://pak.asap.de/';&gt;website&lt;/a&gt;" /> (1) (2)
<#datastore documentation="Documentation of an input!" key="input" scope="READ" mandatory="true" type="STRING"/> (3)
</div>

[...]

Figure 13. Human task being opened in the single command runner

Figure 14. Input Documentation of a human task

1	The documentation is under the `workflowDocu` argument of the `<#command /> tag`.
2	Using advanced options like a link requires to write the HTML tags within the documentation text with the `<` and `>` parts of the tag being replaced with `<` and `>` respectively. These are the escaped character replacements for writing a `<` or `>` as text and not as a beginning or end of a tag.
3	The documentation of `<#datastore />` tag is under the `documentation` argument.

6. Nice to know

6.1. Copying text from documentation

To copy text from the documentation you can simply click on the word you want to copy, as selecting text is not possible.

Following tags will only let you copy their whole content: <td>, <th>, <a> and <code>!

6.2. Inline arguments

You cannot use inline arguments like inline styles or classes!

Any inline argument of HTML tags is ignored, except the href on the <a> tags!

6.3. Applying HTML to the documentation of a workflow

This requires knowledge about how to use the PAK Editor to build workflows.

Documenting a workflow with advanced HTML tags works similar to documenting a java command. You are still restricted by the same HTML logic. You can add the HTML to your workflow documentation like follows:

AddHtmlToWorkflowDocu.bpmn

1	You can simply add HTML tags like this.
2	You can do this with all previously mentioned supported HTML tags.

How to document your commands

1. Introduction

2. Prerequisites

3. Document your command

3.1. Using classes as Commands

3.2. Using methods as commands

4. Writing advanced documentation

4.1. Formatting

4.1.1. Linebreak

4.1.2. Paragraph

4.1.3. Headings

4.1.4. Container

4.1.5. Table

4.2. Styling tags

4.2.1. Making text bold

4.3. Functional tags

4.3.1. Links

4.3.2. Examples

5. Human Task Documentation

5.1. Documenting a human task

6. Nice to know

6.1. Copying text from documentation

6.2. Inline arguments

6.3. Applying HTML to the documentation of a workflow

We are here to help.

3.1. Using classes as Commands

3.2. Using methods as commands

4.1. Formatting

4.1.1. Linebreak

4.1.2. Paragraph

4.1.3. Headings

4.1.4. Container

4.1.5. Table

4.2. Styling tags

4.2.1. Making text bold

4.3. Functional tags

4.3.1. Links

4.3.2. Examples

5.1. Documenting a human task

6.1. Copying text from documentation

6.2. Inline arguments

6.3. Applying HTML to the documentation of a workflow

Sonatype Nexus

Jenkins

Git Hub

Atlassian Confluence

Codebeamer

JFrog Artifactory

Amazon Web Services (AWS)

Atlassian Jira

Git

Generic Human Tasks

Generic Commands

Nexus Maven Command Pool

Artifactory Maven Command Pool

Open API Command Interpreter

Kotlin Command Interpreter

Bpmn Interpreter

Human Task Interpreter

Java Command Interpreter

Core

RocksDB Persistence

PAK online

Command Line App

Workflow Editor

Workflow Executor

Support