Links API documentation pages for Java elements.

Categories

Link / Information System

Tags

Extension

Since

1.0

Renders a link to a Java element in a Javadoc API.

The macros purpose is to specify the reference to the system serving the Javadoc API for the project at one place (as a Confluence shortcut or space property) and reuse this URL throughout the usage of this macro. The body of the macro contains a reference to the Java element to point to.

Macro Editor

Java Elements in Javadoc

To reference the a class, specify the name of the class like this:

com.example.something.MyClass

The following example references a method aMethod():

com.example.something.MyClass.aMethod()

Here an example referencing a method aMethod(String, Class<?>) with generics:

com.example.something.MyClass.aMethod(java.lang.String, java.lang.Class)

Note to specify the parameters fully qualified and that generic type parameters or wildcards are not part of the reference.

This macro does not import Javadoc HTML pages into Confluence to make them searchable. It is used to create a link to an element of the API in a Confluence page. The base URL to the API home is defined by a space property and the relative URL is generated by the information passed to the macro (e.g. the name of the class).

Since projectdoc Toolbox version 1.11 this macro is part of the Information Systems Extension. Prior to that version the macro has been part of the projectdoc Toolbox.

The Since attribute above refers to the version of the extension, not to the version of the projectdoc Toolbox.

Properties

System Identifier

Identifies the connection information via Confluence shortcuts or space properties.

Defaults to javadoc.

The system identifier is checked at three locations

Typically do not change the system identifier provided by the macro (if one is specified). Keep the default value of '${system-id}' as long as you do not need to reference multiple server of the same type in one space. Then set the space property to reference the specific server accordingly. This makes it easier to create new links to artifacts since the system identifier need not to be changed.

The search for the system connection information is conducted as follows. Use the URI discovered first to connect to the server.

Check for a space property url-${system-id}
Check for a space property ${system-id}
Only available with projectdoc Toolbox version 1.11 and up!
Check for a space property shortcut-id-${system-id}.
Lookup the connection information from the shortcut links with the value retrieved from the space property.
Check the shortcut links for a value ${system-id}.
Check application navigator for a value ${system-id}.

If no value is specified at any of the locations above, the macro renders an error message like this:

In this example for a system macro the referenced, but undefined system, is called test-repo.

Specify URL via Space Property

Add the space property url-javadoc and point it to

https://www.example.com/my-project/apidocs

Render Fully Qualified

If checked the element is rendered fully qualified. Otherwise only the element is rendered.

If the flag is unchecked and specified class is

com.example.something.MyClass

only the name of the class, MyClass, will be rendered.

Render Type

If checked the type is rendered. Otherwise only the name of the method is rendered.

Use this if you want to put emphasis on the method.

If you only specify the type and uncheck this box, nothing will be rendered.

Render Parameters

If checked the method parameters are rendered. Otherwise only the name of the method is rendered.

If checked, instead of

com.example.something.MyClass.aMethod(java.lang.String, java.lang.Class)

only the following will be rendered as the link's label:

com.example.something.MyClass.aMethod

Label

The label for the link.

Defaults to the element name specified in the body of this macro.

Details

Autoconvert

To create the macro authors may simply paste the URI to the Java element to the editor. All is needed is a configuration of the Javadoc base URI. For more information on this topic, please refer to Autoconvert Information System URIs.

Autoconvert does not work nicely if the pasted URL contains spaces. You may replace spaces either with the '+' sign or with the character '%20'.

Assume the space property 'url-javadoc' is set to 'https://www.smartics.eu/de.smartics.util/smartics-commons/0.5.2/apidocs/de/smartics/util/lang/Arg.html#checkNotBlank(java.lang.String, T)'.

Now assume the following URI is pasted to the editor (one line!).

https://www.smartics.eu/de.smartics.util/smartics-commons/0.5.2/apidocs/
  de/smartics/util/lang/Arg.html#checkNotBlank(java.lang.String, T)

Since the URI contains a space (just before the last parameter of type T), the result is this:

Notice that the effect is the similar if you do not use the Javadoc Macro Autoconverter:

Replace the space with a '+' sign (again: one line!)

https://www.smartics.eu/de.smartics.util/smartics-commons/0.5.2/apidocs/
  de/smartics/util/lang/Arg.html#checkNotBlank(java.lang.String,+T)

and the result will be

Related macros

The following macros help with referencing resources on other information servers:

Enterprise Architect Image Link Macro: Renders an image generated from an Enterprise Architect diagram, transcluded from a server.
HTML Snippet Macro: Transclude HTML content from a remote server.
Nexus Link Macro: Renders a link to an artifact stored on a Nexus server.
System Image Link Macro: Renders an image transcluded from a remote server.
System Link Macro: Links to a resource on a server.
System Transclusion Macro: Transclude content from a resource from a remote system.
Text Snippet Macro: Transclude text content from a remote server.

Javadoc Link Macro