Links to SPL artifacts

In a toolkit, you can use SPLDOC to mark up links to toolkits, namespaces, operators, functions, types, and SPL files. The name of the artifact is enclosed in square brackets: [LinuxPipe].

When multiple SPL artifacts share a name, or the artifact is in another toolkit, or the artifact is a toolkit or namespace, you must qualify the artifacts in any links to them. If these artifacts are not qualified in the links, the spl-make-doc command generates an error message.

SPL artifacts links not qualified by type or namespace
This example creates a link from the LinuxPipe text to the document that is generated for that primitive operator.
/**
The [LinuxPipe] operator runs a Linux pipe command on the contents of the 
input stream and emits the results from 'stdout' (and optionally, 'stderr') 
on one or two output streams.
*/
The spl-make-doc command generates HTML similar to this code.
<p>The <a href="sample$LinuxPipe.html">LinuxPipe</a> operator runs 
a Linux pipe command on the contents of the input stream and emits 
the results from <tt>stdout</tt> (and optionally, <tt>stderr</tt>) on one 
or two output streams.
</p>
Qualify SPL artifacts by namespace
When multiple SPL artifacts have the same name in different namespaces, you can eliminate ambiguity by qualifying the artifact by the namespace. You must also qualify links with a namespace when you link to an artifact in another toolkit. This example creates a link to the document that is generated for the LinuxPipe primitive operator in the sample namespace, where the SPL artifact name includes the namespace.
/**
The [sample::LinuxPipe] operator runs a Linux pipe command on the contents 
of the input stream and emits the results from 'stdout' (and optionally, 
'stderr') on one or two output streams.
*/
To define a link to an artifact of a specific type without including a specific namespace, use a wildcard to represent the namespace. The following example defines a link to the document that contains the getMaximum function in any namespace in the toolkit. If this function is defined in multiple namespaces in the toolkit, an error message is output to report the ambiguity:
[function:*::getMaximum]
To define a link to an artifact in the default namespace, use the namespace delimiter (::) with a blank namespace. The following example defines a link to an SPL artifact named getMaximum in the default namespace:
[::getMaximum]
Qualify SPL artifacts by type
When multiple SPL artifacts share a name in the same namespace, you can qualify the link text by the artifact type. When the artifact is a toolkit or namespace, you must include the artifact type in the link text. You can specify the following artifact types in your links.
  • Toolkits (specify toolkit)
  • Namespaces (specify namespace)
  • Operators (specify operator)
  • Functions (specify function)
  • Types (specify type)
  • SPL files (specify compilationunit)

The following example shows a link to an operator that shares the LinuxPipe name with a function. The operator and the function are in the sample namespace. 

/**
The [operator:sample::LinuxPipe] operator runs a Linux pipe command on the 
contents of the input stream and emits the results from 'stdout' (and 
optionally, 'stderr') on one or two output streams.
*/

The spl-make-doc command generates HTML similar to this code.

<p>The <a href="sample$LinuxPipe.html">operator:sample::LinuxPipe</a> operator 
runs a Linux pipe command on the contents of the input stream and emits 
the results from <tt>stdout</tt> (and optionally, <tt>stderr</tt>) on one or 
two output streams.
</p>

This example creates a link to the documentation for the yourToolkit toolkit.

/**
The [toolkit:yourToolkit] toolkit is referenced.
*/

This example creates a link to the documentation for the yourNamespace namespace.

/**
The [namespace:yourNamespace] namespace is referenced.
*/
Links with a label
The following example creates a link to the sample::LinuxPipe operator that is accessed through the LinuxPipe label.
[sample::LinuxPipe|LinuxPipe]