Creating Topic Links

Both the TechWriter comment models and Annotation editor support creating topic links that allow the readers of your documentation to navigate from one topic through a reference to another topic. If you are creating topic links using the Annotation editor, it takes care of all of the details for you. But if you are manually creating the links directly within your web service comments, you will need to know the details on the syntax of the target of your link.

While JavaDoc, XHTML and XML Comments all use different tags for formatting links, the syntax of the link target is independent of the comment model. Link targets that start with http: or https: are considered external link targets and should represent a URL to a web page. Link targets that do not start with http: or https: are considered topic link targets and should have the following syntax:

<Item Type>.<Web Service Name>[#<Item Name>]

where

<Item Type> is type of item that is being linked to. This part of the link target is required and must have one of the following values:

Web+Services
Methods
Elements
Attributes
Complex+Types
Simple+Types

<Web Service Name> is the friendly name given to the web service containing the topic that is being linked to. This part of the link target is required.

<Item Name> is the name of the item whose topic is being linked to. If this part of the link target is omitted, the link target will reference the summary topic for the specified item type.

Link targets must not contain any spaces. If any of the names used to create the link target do have spaces, they should be replaced with plus sign (+) characters.

See the table below for example topic links.

Type of Topic Link Example

Web Service Summary Topic Web+Services.MapPoint

Method Summary Topic Methods.MapPoint

Method Topic Methods.MapPoint#GetClientToken

Element Topic Elements.MARCXML#collection

Attribute Topic Attributes.MARCXML#id+[type+collectionType]

Complex Type Topic Complex+Type.MARCXML#collectionType

Simple Type Topic Simple+Type.MARCXML#tagDataType

Type of Topic Link	Example
Web Service Summary Topic	Web+Services.MapPoint
Method Summary Topic	Methods.MapPoint
Method Topic	Methods.MapPoint#GetClientToken
Element Topic	Elements.MARCXML#collection
Attribute Topic	Attributes.MARCXML#id+[type+collectionType]
Complex Type Topic	Complex+Type.MARCXML#collectionType
Simple Type Topic	Simple+Type.MARCXML#tagDataType